Merge pull request #818 from pybamm-team/issue-613-citing

Issue 613 citing

.gitignore

@@ -11,6 +11,7 @@
 !requirements*
 !LICENSE.txt
 !CMakeLists.txt
+!pybamm/CITATIONS.txt
 !pybamm/input/**/*.csv
 
 # running files

CHANGELOG.md

@@ -7,7 +7,8 @@
 -   Added capacitance effects to lithium-ion models ([#842](https://github.com/pybamm-team/PyBaMM/pull/842))
 -   Added NCA parameter set ([#824](https://github.com/pybamm-team/PyBaMM/pull/824))
 -   Added functionality to `Solution` that automatically gets `t_eval` from the data when simulating drive cycles and performs checks to ensure the output has the required resolution to accurately capture the input current ([#819](https://github.com/pybamm-team/PyBaMM/pull/819))
--   Added options to export a solution to matlab or csv ([#811](https://github.com/pybamm-team/PyBaMM/pull/811))
+-   Added `Citations` object to print references when specific functionality is used ([#818](https://github.com/pybamm-team/PyBaMM/pull/818))
+-   Updated `Solution` to allow exporting to matlab and csv formats ([#811](https://github.com/pybamm-team/PyBaMM/pull/811))
 -   Allow porosity to vary in space ([#809](https://github.com/pybamm-team/PyBaMM/pull/809))
 -   Added functionality to solve DAE models with non-smooth current inputs ([#808](https://github.com/pybamm-team/PyBaMM/pull/808))
 -   Added functionality to simulate experiments and testing protocols ([#807](https://github.com/pybamm-team/PyBaMM/pull/807))

README.md

@@ -46,6 +46,32 @@ For instructions on installing PyBaMM on Mac OS distributions, please see [here]
 We recommend using Windows Subsystem for Linux to install PyBaMM on a Windows OS, for
 instructions please see [here](INSTALL-WINDOWS.md)
 
+## Citing PyBaMM
+
+If you use PyBaMM in your work, please cite our paper
+
+"Sulzer, V., Marquis, S. G., Timms, R., Robinson, M., & Chapman, S. J. (2020). Python Battery Mathematical Modelling (PyBaMM). _ECSarXiv. February, 7_."
+
+You can use the bibtex
+
+```
+@article{sulzer2020python,
+  title={Python Battery Mathematical Modelling (PyBaMM)},
+  author={Sulzer, Valentin and Marquis, Scott G and Timms, Robert and Robinson, Martin and Chapman, S Jon},
+  journal={ECSarXiv. February},
+  volume={7},
+  year={2020}
+}
+```
+
+We would be grateful if you could also cite the relevant papers. These will change depending on what models and solvers you use. To find out which papers you should cite, add the line
+
+```python3
+pybamm.print_citations()
+```
+
+to the end of your script. This will print bibtex information to the terminal; passing a filename to `print_citations` will print the bibtex information to the specified file instead. A list of all citations can also be found in the [citations file](pybamm/CITATIONS.txt). In particular, PyBaMM relies heavily on [CasADi](https://web.casadi.org/publications/).
+
 ## How can I contribute to PyBaMM?
 
 If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these [guidelines](CONTRIBUTING.md) first.

docs/index.rst

@@ -34,6 +34,7 @@ Contents
     source/processed_variable
     source/util
     source/simulation
+    source/citations
     source/parameters_cli
 
 Examples

docs/source/citations.rst

@@ -0,0 +1,7 @@
+Citations
+=========
+
+.. autoclass:: pybamm.Citations
+  :members:
+
+.. autofunction:: pybamm.print_citations

examples/scripts/DFN.py

@@ -30,7 +30,7 @@
 
 # solve model
 t_eval = np.linspace(0, 3600, 100)
-solver = model.default_solver
+solver = pybamm.CasadiSolver()
 solver.rtol = 1e-3
 solver.atol = 1e-6
 solution = solver.solve(model, t_eval)

pybamm/CITATIONS.txt

@@ -0,0 +1,125 @@
+@Article{Andersson2019,
+  author = {Joel A E Andersson and Joris Gillis and Greg Horn
+            and James B Rawlings and Moritz Diehl},
+  title = {{CasADi} -- {A} software framework for nonlinear optimization
+           and optimal control},
+  journal = {Mathematical Programming Computation},
+  volume = {11},
+  number = {1},
+  pages = {1--36},
+  year = {2019},
+  publisher = {Springer},
+  doi = {10.1007/s12532-018-0139-4}
+}
+
+@article{Chen2020,
+author = {Chen, Chang-Hui and Brosa Planella, Ferran and O'Regan, Kieran and Gastol, Dominika and Widanage, W. Dhammika and Kendrick, Emma},
+title = {{Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models}},
+journal = {Submitted for publication},
+year = {2020}
+}
+
+@article{doyle1993modeling,
+  title={Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell},
+  author={Doyle, M and Fuller, TF and Newman, J},
+  journal={Journal of the Electrochemical society},
+  volume={140},
+  number={6},
+  pages={1526--1533},
+  year={1993},
+  publisher={The Electrochemical Society},
+  note = {\href{ http://dx.doi.org/10.1149/1.2221597}{doi: 10.1149/1.2221597}},
+}
+
+@techreport{hindmarsh2000pvode,
+  title={The {PVODE} and {IDA} algorithms},
+  author={Hindmarsh, AC},
+  year={2000},
+  institution={Lawrence Livermore National Lab., CA (US)},
+  note = {\href{ https://www.osti.gov/biblio/802599}{doi:10.2172/802599}},
+}
+
+@article{hindmarsh2005sundials,
+  title={SUNDIALS: Suite of nonlinear and differential/algebraic equation solvers},
+  author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S},
+  journal={ACM Transactions on Mathematical Software (TOMS)},
+  volume={31},
+  number={3},
+  pages={363--396},
+  year={2005},
+  publisher={ACM New York, NY, USA}
+}
+
+@article{kim2011multi,
+  title={Multi-domain modeling of lithium-ion batteries encompassing multi-physics in varied length scales},
+  author={Kim, Gi-Heon and Smith, Kandler and Lee, Kyu-Jin and Santhanagopalan, Shriram and Pesaran, Ahmad},
+  journal={Journal of the electrochemical society},
+  volume={158},
+  number={8},
+  pages={A955--A969},
+  year={2011},
+  publisher={The Electrochemical Society}
+}
+
+@article{marquis2019asymptotic,
+title={An asymptotic derivation of a single particle model with electrolyte},
+author={Marquis, Scott G and Sulzer, Valentin and Timms, Robert and Please, Colin P and Chapman, S Jon},
+journal={Journal of The Electrochemical Society},
+volume={166},
+number={15},
+pages={A3693--A3706},
+year={2019},
+publisher={The Electrochemical Society}
+}
+
+@article{scikits-odes,
+  year  = {2018},
+  month = {feb},
+  publisher = {The Open Journal},
+  volume = {3},
+  number = {22},
+  pages = {165},
+  author = {Malengier, B and Ki{\v{s}}on, P and Tocknell, J and Abert, C and Bruckner, F and Bisotti, M-A},
+  title = {{ODES}: a high level interface to {ODE} and {DAE} solvers},
+  journal = {The Journal of Open Source Software},
+  note = {\href{ http://dx.doi.org/10.21105/joss.00165}{doi: 10.21105/joss.00165}},
+}
+
+@article{virtanen2020scipy,
+  title={SciPy 1.0: fundamental algorithms for scientific computing in Python},
+  author={Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and others},
+  journal={Nature Methods},
+  pages={1--12},
+  year={2020},
+  publisher={Nature Publishing Group}
+}
+
+@article{sulzer2019physical,
+  title={Faster Lead-Acid Battery Simulations from Porous-Electrode Theory: Part I. Physical Model},
+  author={Sulzer, Valentin and Chapman, S Jon and Please, Colin P and Howey, David A and Monroe, Charles W},
+  journal={Journal of The Electrochemical Society},
+  volume={166},
+  number={12},
+  pages={A2363--A2371},
+  year={2019},
+  publisher={The Electrochemical Society}
+}
+
+@article{sulzer2019asymptotic,
+  title={Faster Lead-Acid Battery Simulations from Porous-Electrode Theory: Part II. Asymptotic Analysis},
+  author={Sulzer, Valentin and Chapman, S Jon and Please, Colin P and Howey, David A and Monroe, Charles W},
+  journal={Journal of The Electrochemical Society},
+  volume={166},
+  number={12},
+  pages={A2372--A2382},
+  year={2019},
+  publisher={The Electrochemical Society}
+}
+
+@article{sulzer2020python,
+title={Python Battery Mathematical Modelling (PyBaMM)},
+author={Sulzer, Valentin and Marquis, Scott G and Timms, Robert and Robinson, Martin and Chapman, S Jon},
+journal={ECSarXiv. February},
+volume={7},
+year={2020}
+}

pybamm/__init__.py

@@ -60,6 +60,7 @@ def version(formatted=False):
 from .util import get_parameters_filepath
 from .logger import logger, set_logging_level
 from .settings import settings
+from .citations import Citations, citations, print_citations
 
 #
 # Classes for the Expression Tree

pybamm/citations.py

@@ -0,0 +1,100 @@
+#
+# Bibliographical information for PyBaMM
+# Inspired by firedrake/PETSc citation workflow
+# https://www.firedrakeproject.org/citing.html
+#
+import pybamm
+import os
+
+
+class Citations:
+
+    """Entry point to citations management.
+    This object may be used to record Bibtex citation information and then register that
+    a particular citation is relevant for a particular simulation. For a list of all
+    possible citations, see `pybamm/CITATIONS.txt`
+
+    Examples
+    --------
+    >>> import pybamm
+    >>> pybamm.citations.register("sulzer2020python")
+    >>> pybamm.print_citations("citations.txt")
+    """
+
+    def __init__(self):
+        self.read_citations()
+        self._reset()
+
+    def _reset(self):
+        "Reset citations to default only (only for testing purposes)"
+        # Initialize empty papers to cite
+        self._papers_to_cite = set()
+        # Register the PyBaMM paper
+        self.register("sulzer2020python")
+
+    def read_citations(self):
+        "Read the citations text file"
+        self._all_citations = {}
+
+        citations_file = os.path.join(pybamm.root_dir(), "pybamm", "CITATIONS.txt")
+        citation = ""
+        start = True
+
+        for line in open(citations_file):
+            # if start is true, we need to find the key
+            if start is True:
+                # match everything between { and , in the first line to get the key
+                brace_idx = line.find("{")
+                comma_idx = line.find(",")
+                key = line[brace_idx + 1 : comma_idx]
+                # turn off start as we now have the right key
+                start = False
+            citation += line
+            # blank line means next block, add citation to dictionary and
+            # reset everything
+            if line == "\n":
+                self._all_citations[key] = citation
+                citation = ""
+                start = True
+
+        # add the final citation
+        self._all_citations[key] = citation
+
+    def register(self, key):
+        """Register a paper to be cited. The intended use is that :meth:`register`
+        should be called only when the referenced functionality is actually being used.
+
+        Parameters
+        ----------
+        key : str
+            The key for the paper to be cited
+        """
+        if key not in self._all_citations:
+            raise KeyError("'{}' is not a known citation".format(key))
+        self._papers_to_cite.add(key)
+
+    def print(self, filename=None):
+        """Print all citations that were used for running simulations.
+
+        Parameters
+        ----------
+        filename : str, optional
+            Filename to which to print citations. If None, citations are printed to the
+            terminal.
+        """
+        citations = ""
+        for key in self._papers_to_cite:
+            citations += self._all_citations[key] + "\n"
+        if filename is None:
+            print(citations)
+        else:
+            with open(filename, "w") as f:
+                f.write(citations)
+
+
+def print_citations(filename=None):
+    "See :meth:`Citations.print`"
+    pybamm.citations.print(filename)
+
+
+citations = Citations()

pybamm/expression_tree/operations/convert_to_casadi.py

@@ -11,6 +11,8 @@ class CasadiConverter(object):
     def __init__(self, casadi_symbols=None):
         self._casadi_symbols = casadi_symbols or {}
 
+        pybamm.citations.register("Andersson2019")
+
     def convert(self, symbol, t=None, y=None, u=None):
         """
         This function recurses down the tree, converting the PyBaMM expression tree to

pybamm/models/full_battery_models/lead_acid/full.py

@@ -49,6 +49,8 @@ def __init__(self, options=None, name="Full model", build=True):
         if build:
             self.build_model()
 
+        pybamm.citations.register("sulzer2019physical")
+
     def set_porosity_submodel(self):
         self.submodels["porosity"] = pybamm.porosity.Full(self.param)
 

pybamm/models/full_battery_models/lead_acid/higher_order.py

@@ -57,6 +57,8 @@ def __init__(self, options=None, name="Composite model", build=True):
         if build:
             self.build_model()
 
+        pybamm.citations.register("sulzer2019asymptotic")
+
     def set_current_collector_submodel(self):
         cc = pybamm.current_collector
 

pybamm/models/full_battery_models/lead_acid/loqs.py

@@ -52,6 +52,8 @@ def __init__(self, options=None, name="LOQS model", build=True):
         if self.options["dimensionality"] == 0:
             self.use_jacobian = False
 
+        pybamm.citations.register("sulzer2019asymptotic")
+
     def set_external_circuit_submodel(self):
         """
         Define how the external circuit defines the boundary conditions for the model,

pybamm/models/full_battery_models/lithium_ion/dfn.py

@@ -48,6 +48,8 @@ def __init__(self, options=None, name="Doyle-Fuller-Newman model", build=True):
         if build:
             self.build_model()
 
+        pybamm.citations.register("doyle1993modeling")
+
     def set_porosity_submodel(self):
 
         self.submodels["porosity"] = pybamm.porosity.Constant(self.param)

pybamm/models/full_battery_models/lithium_ion/spm.py

@@ -48,6 +48,8 @@ def __init__(self, options=None, name="Single Particle Model", build=True):
         if build:
             self.build_model()
 
+        pybamm.citations.register("marquis2019asymptotic")
+
     def set_porosity_submodel(self):
 
         self.submodels["porosity"] = pybamm.porosity.Constant(self.param)

pybamm/models/full_battery_models/lithium_ion/spme.py

@@ -51,6 +51,8 @@ def __init__(
         if build:
             self.build_model()
 
+        pybamm.citations.register("marquis2019asymptotic")
+
     def set_porosity_submodel(self):
 
         self.submodels["porosity"] = pybamm.porosity.Constant(self.param)