Add citations management functions (#14)

* Add citations management functions

* Add a test

Author: connorjward

petsctools/__init__.py

@@ -14,6 +14,7 @@
 # is not available then attempting to access these attributes will raise an
 # informative error.
 if PETSC4PY_INSTALLED:
+    from .citation import add_citation, cite, print_citations_at_exit  # noqa: F401
     from .config import get_blas_library  # noqa: F401
     from .init import (  # noqa: F401
         InvalidEnvironmentException,
@@ -37,6 +38,9 @@
 
     def __getattr__(name):
         petsc4py_attrs = {
+            "add_citation",
+            "cite",
+            "print_citations_at_exit",
             "get_blas_library",
             "InvalidEnvironmentException",
             "InvalidPetscVersionException",

petsctools/citation.py

@@ -0,0 +1,70 @@
+"""Module containing functions for registering citations through PETSc.
+
+The functions in this module may be used to record Bibtex citation
+information and then register that a particular citation is
+relevant for a particular computation.  It hooks up with PETSc's
+citation registration mechanism, so that running with
+``-citations`` does the right thing.
+
+Example usage::
+
+    petsctools.add_citation("key", "bibtex-entry-for-my-funky-method")
+
+    ...
+
+    if using_funky_method:
+        petsctools.cite("key")
+
+"""
+
+from petsc4py import PETSc
+
+
+_citations_database = {}
+
+
+def add_citation(cite_key: str, entry: str) -> None:
+    """Add a paper to the database of possible citations.
+
+    Parameters
+    ----------
+    cite_key :
+        The key to use.
+    entry :
+        The bibtex entry.
+
+    """
+    _citations_database[cite_key] = entry
+
+
+def cite(cite_key: str) -> None:
+    """Cite a paper.
+
+    The paper should already have been added to the citations database using
+    `add_citation`.
+
+    Parameters
+    ----------
+    cite_key :
+        The key of the relevant citation.
+
+    Raises
+    ------
+    KeyError :
+        If no such citation is found in the database.
+
+    """
+    if cite_key in _citations_database:
+        citation = _citations_database[cite_key]
+        PETSc.Sys.registerCitation(citation)
+    else:
+        raise KeyError(
+            f"Did not find a citation for '{cite_key}', please add it to the "
+            "citations database"
+        )
+
+
+def print_citations_at_exit() -> None:
+    """Print citations at the end of the program."""
+    # We devolve to PETSc for actually printing citations.
+    PETSc.Options()["citations"] = None

tests/test_citations.py

@@ -0,0 +1,15 @@
+import pytest
+
+import petsctools
+
+
+@pytest.mark.skipnopetsc4py
+def test_cannot_cite_nonexistent_citation():
+    with pytest.raises(KeyError):
+        petsctools.cite("nonexistent")
+
+
+@pytest.mark.skipnopetsc4py
+def test_cite_citation():
+    petsctools.add_citation("mykey", "myentry")
+    petsctools.cite("mykey")