Merge pull request #655 from marrink-lab/common_citations

Add non-forcefield-specific citations to the root of the data directory

vermouth/citation_parser.py

@@ -34,8 +34,8 @@ class BibTexDirector():
     check for missing fields or invalid fields. All
     fields are accepted and no fields are required.
     """
-    def __init__(self, force_field):
-        self.force_field = force_field
+    def __init__(self):
+        self.citations = {}
         self.known_entries = ["article",
                               "book",
                               "booklet",
@@ -153,26 +153,29 @@ def parse_entry(self, entry_string):
         cite_key, entry_string = self.pop_key(entry_string)
         field_dict = dict(self.extract_fields(entry_string))
         field_dict["type"] = entry_type
-        self.force_field.citations[cite_key] = field_dict
+        self.citations[cite_key] = field_dict
 
     def parse(self, lines):
         """
         Given lines from a bibtex file parse them and update
         the force-field citation instance variable.
         """
-        # convert file to string deleting end of line charcters
+        # convert file to string deleting end of line characters
         citations_string = self.prepare_file(lines)
         # extract the entries from the string
         entries = list(self.find_entries(citations_string))
         entries.append(len(citations_string))
         # parse each entry to generate a citation
         for idx, jdx in zip(entries[:-1], entries[1:]):
             self.parse_entry(citations_string[idx:jdx])
-        return self.force_field.citations
-
-def read_bib(lines, force_field):
-    director = BibTexDirector(force_field=force_field)
-    return director.parse(iter(lines))
+        return self.citations
+
+def read_bib(lines, force_field=None):
+    director = BibTexDirector()
+    director.parse(iter(lines))
+    if force_field:
+        force_field.citations = director.citations
+    return director.citations
 
 def citation_formatter(citation, title=False):
     """

vermouth/data/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 University of Groningen
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .data import *

vermouth/data/citations.bib

@@ -0,0 +1,22 @@
+@article{MDTraj,
+    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
+    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
+    journal={Biophysical Journal},
+    volume={109},
+    number={8},
+    pages={1528 -- 1532},
+    year={2015},
+    doi={10.1016/j.bpj.2015.08.015}
+}
+@article{vermouth,
+    title={Martinize2 and Vermouth: Unified Framework for Topology Generation},
+    url={http://dx.doi.org/10.7554/eLife.90627.2},
+    doi={10.7554/elife.90627.2},
+    journal={elife},
+    volume={12},
+    pages={RP90627}
+    publisher={eLife Sciences Publications, Ltd},
+    author={Kroon, Peter C and Grunewald, F and Barnoud, J and van Tilburg, M and Souza, Paulo CT and Wassenaar, Tsjerk A and Marrink, Siewert J},
+    year={2024},
+    month=jun
+}

vermouth/data/data.py

@@ -0,0 +1,43 @@
+# Copyright 2025 University of Groningen
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .. import DATA_PATH
+from ..citation_parser import read_bib
+
+
+def _read_quote_file(filehandle):
+    """
+    Iterates over `filehandle`, and yields all strings that are not empty.
+
+    Parameters
+    ----------
+    filehandle: collections.abc.Iterable[str]
+        A file opened for reading.
+
+    Yields
+    ------
+    str
+        All stripped elements of `filehandle` that are not empty.
+    """
+    for line in filehandle:
+        line = line.strip()
+        if line:
+            yield line
+
+
+with open(DATA_PATH/'citations.bib') as citation_file:
+    COMMON_CITATIONS = read_bib(citation_file)
+
+with open(DATA_PATH/'quotes.txt') as quotes_file:
+    QUOTES = list(_read_quote_file(quotes_file))

vermouth/data/force_fields/elnedyn21/citations.bib

@@ -52,13 +52,3 @@ @article{M2polarizable
   year={2010},
   publisher={Public Library of Science}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/elnedyn22/citations.bib

@@ -52,13 +52,3 @@ @article{M2polarizable
   year={2010},
   publisher={Public Library of Science}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/elnedyn22p/citations.bib

@@ -52,13 +52,3 @@ @article{M2polarizable
   year={2010},
   publisher={Public Library of Science}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/martini22/citations.bib

@@ -52,13 +52,3 @@ @article{M2polarizable
   year={2010},
   publisher={Public Library of Science}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/martini22p/citations.bib

@@ -52,13 +52,3 @@ @article{M2polarizable
   year={2010},
   publisher={Public Library of Science}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/martini3001/citations.bib

@@ -18,16 +18,6 @@ @article{Martini3smallmolecules
   year={2022},
   publisher={Wiley Online Library}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}
 @article{M3_GO,
 title={GōMartini 3: From large conformational changes in proteins to environmental bias corrections},
 author={Souza, Paulo C. T. and Araujo, Luis P. Borges and Brasnett, Chris and Moreira, Rodrigo A. and Grunewald, Fabian and Park, Peter and Wang, Liguo and Razmazma, Hafez and Borges-Araujo, Ana C. and Cofas-Vargas, Luis F. and Monticelli, Luca and Mera-Adasme, Raul and Melo, Manuel N. and Wu, Sangwook and Marrink, Siewert J. and Poma, Adolfo B. and Thallmair, Sebastian},

vermouth/data/force_fields/martini30b32/citations.bib

@@ -3,13 +3,3 @@ @misc{Martini3Beta
   author={Souza, Paulo C T and Marrink, Siewert Jan},
   year={2020}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/data/force_fields/martini30dev/citations.bib

@@ -3,13 +3,3 @@ @misc{Martini3Beta
   author={Souza, Paulo C T and Marrink, Siewert Jan},
   year={2020}
 }
-@article{MDTraj,
-    title={MDTraj: A Modern Open Library for the Analysis of Molecular Dynamics Trajectories},
-    author={McGibbon, Robert T. and Beauchamp, Kyle A. and Harrigan, Matthew P. and Klein, Christoph and Swails, Jason M. and Hernández, Carlos X.  and Schwantes, Christian R. and Wang, Lee-Ping and Lane, Thomas J. and Pande, Vijay S.},
-    journal={Biophysical Journal},
-    volume={109},
-    number={8},
-    pages={1528 -- 1532},
-    year={2015},
-    doi={10.1016/j.bpj.2015.08.015}
-}

vermouth/forcefield.py

@@ -25,6 +25,7 @@
 from . import DATA_PATH
 
 FORCE_FIELD_PARSERS = {'.rtp': read_rtp, '.ff': read_ff, '.bib': read_bib}
+# All data files that are in the root DATA_PATH, and apply to all force fields.
 
 # Cache the force fields.
 # It should only be used by the get_native_force_field function, else it would
@@ -54,6 +55,7 @@ class ForceField:
     blocks: dict
     links: list
     modifications: dict
+    citations: dict
     renamed_residues: dict
     name: str
     variables: dict
@@ -76,6 +78,14 @@ def __init__(self, directory=None, name=None):
             msg = 'At least one of `directory` or `name` must be provided.'
             raise TypeError(msg)
 
+    def __str__(self):
+        return f'ForceField({self.name})'
+
+    def __eq__(self, other):
+        # Note, we cannot compare blocks/links/modifications, since those
+        # compare their forcefields for equality.
+        return isinstance(other, self.__class__) and self.name == other.name
+
     def read_from(self, directory):
         """
         Populate or update the force field from a directory.
@@ -85,9 +95,12 @@ def read_from(self, directory):
         """
         source_files = iter_force_field_files(directory)
         for source in source_files:
-            extension = os.path.splitext(source)[-1]
-            with open(source) as infile:
-                FORCE_FIELD_PARSERS[extension](infile, self)
+            self._read_from_file(source)
+
+    def _read_from_file(self, path):
+        extension = os.path.splitext(path)[-1]
+        with open(path) as infile:
+            FORCE_FIELD_PARSERS[extension](infile, self)
 
     @property
     def reference_graphs(self):

vermouth/gmx/topology.py

@@ -2,13 +2,14 @@
 I/O of topology parameters that are not molecules.
 """
 import itertools
-from collections import namedtuple
+from collections import namedtuple, ChainMap
 import textwrap
 import vermouth
 from vermouth.file_writer import deferred_open
 from vermouth.citation_parser import citation_formatter
 from ..log_helpers import StyleAdapter, get_logger
 from .itp import _interaction_sorting_key
+from ..data import COMMON_CITATIONS
 
 LOGGER = StyleAdapter(get_logger(__name__))
 
@@ -179,6 +180,10 @@ def write_gmx_topology(system,
     )
     for moltype, molecules in molecule_groups:
         molecule = next(molecules)
+        if molecule.force_field is not None:
+            citation_map = ChainMap(molecule.force_field.citations, COMMON_CITATIONS)
+        else:
+            citation_map = COMMON_CITATIONS
         if moltype not in moltype_written:
             # A given moltype can appear more than once in the sequence of
             # molecules, without being uninterupted by other moltypes. Even in
@@ -189,7 +194,7 @@ def write_gmx_topology(system,
                 header.append("Please cite the following papers:")
                 for citation in molecule.citations:
                     cite_string = citation_formatter(
-                        molecule.force_field.citations[citation]
+                        citation_map[citation]
                     )
                     LOGGER.info("Please cite: " + cite_string)
                     header.append(cite_string)

vermouth/molecule.py

@@ -356,7 +356,7 @@ def __init__(self, *args, **kwargs):
         self.nrexcl = kwargs.pop('nrexcl', None)
         super().__init__(*args, **kwargs)
         self.interactions = defaultdict(list)
-        self.citations = set()
+        self.citations = {'vermouth'}  # This is part of martinize2/vermouth, so you should cite it!
         # {loglevel: {entry: [fmt_args]}}
         self.log_entries = defaultdict(lambda: defaultdict(list))
         self.max_node = None