Tag PyBaMM citations

[brosaplanella]

Summary
The way citations are printed now (all together) can make it quite hard for an inexperienced user to know why the need to cite each reference. It would be good to add a tag when registering PyBaMM citations and also some extra functionality that, when printing the citations, reads the tags and groups them in a more meaningful way. For example, we could print some sort of list or table that lists:

• Model: Fuller1994
• Parameters: Chen2020
• Solver: Andersson 2019
  and so on...

Please add your comments and suggestions

Motivation
Make it easier for new or inexperienced users to know what's the purpose of each reference, which might lead in them just dumping the citations in their papers all together. Adding this functionality should lead to higher quality citations in the papers.

[rtimms]

I think this sounds great! At the moment the result of print_citations() can be a bit verbose and it's not super readable. Maybe it would be good to print a table/list like you suggest and then generate a .bib file (it looks like you can do this by passing a filename, but perhaps it should print something in cwd if no filename is passed). Then we could print the table/list like you have above along with a message saying a bib file as been generated. If its possible to automate, you could also add something the "note" field of the bibtex entry explaining where the citation was used.

[brosaplanella]

Maybe we could rename the current print method to print_to_bibtex, as I think it is a useful feature for people using LaTeX.

For those who don't, maybe we could use a more user friendly function. I think the list/table would be useful to list the tags, but then we should provide them with the full reference somewhere. Options that I can think of:

• Point them to the documentation.
• Print formatted citation from the Bibtex file.

Thoughts?

[rtimms]

Is there an easy way to automatically print the citation in a nice way from a bibtex file? If so, it would be nice to generate a pdf or similar with all the citations and what they are used for. Maybe it could also print some other useful info like current version number etc. so that it also serves as a helpful document for reproducing results. I like the option of printing to bibtex, but maybe you are right - it isn't most useful for everyone.

[brosaplanella]

There a few packages (see this Stackoverflow post) but it seems that none is great. Maybe the closest one is Pybtex but doesn't seem to be that active either...

[brosaplanella]

Just took another look and there has been a new release of Pybtex. In my opinion, this would be the best way to render the references nicely.

Does this sound like a good idea or would it be better to not add another dependency for such a minor thing?

[Saransh-cpp]

I was following this and the mentioned issue, are you looking to create a new method in Citations class to print citations in a better way? The print method (which you are thinking of renaming) already uses pybtex as described in the #1330 .

And as I was exploring the citations section, pybamm.citations.register("Sulzer2020") gives me a key error. I followed ahead to check, the read_citations method reads all the citations and writes it down in a map so I tried running that method first but still the same error. How can I fix this? and I'll be happy to help and solve this issue.

[rtimms]

The goal of this issue was to somehow tag citations with where they are used in the code (e.g. are they used in a solver or a particular model) so that users know why they need to cite that paper. I think we are happy with how the citations are printed now that we are using pybtex. Ideally the citations would come with a note saying where they were used, or we could print some kind of table or something saying which citations were used where.

Some of the reference keys were updated in #1330 to make them all consistent - are you up to date with the latest develop branch? This might be the cause of the key error.

[Saransh-cpp]

Yes, after the pulling the branch it works, thank you.

[ayeankit]

Hello @tinosulzer and @tinosulzer , I want to work on this issue but I am new to this repo and I need help. Please assign me this.

[rtimms]

At the moment we register citations (e.g. here) in various parts of the code, which then get logged using the Citations class, see here. You can then print out which papers you need to cite based on what code you used.

It would be helpful to also log somehow where the citations were registered. Probably best in some high-level way like by the folder inside pybamm that the code lives in (models, solvers, plotting, etc.). This could show up as a note in the bibtex entry, or we could print citations organised by folder.

[agriyakhetarpal]

Hi @rtimms, I'm not sure how a table would be implemented but perhaps a modification or improvement for the pybamm.citations.register() method could be to add another argument (or other functionality) to return the __qualname__ of the class it was called from, such that it can log where the citations were registered like you suggest

def(register, key, cited_from):
# additional logic

and then after calling pybamm.citations.register(), say, for the DFN lithium-ion model:

>>> pybamm.print_citations()

returns

[6] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149[/2.0341915jes.](https://file+.vscode-resource.vscode-cdn.net/2.0341915jes.)

cited due to the use of pybamm.lithium_ion.DFN()

Another way to do the same is to wrap the register() function in a class decorator @register_citation with a custom metaclass to alter the __call__ method which can then be called whenever a model is initialised. I am happy to work on this or any suggestions you may have (provided @ayeankit gives me a go-ahead, since they are assigned to this issue currently and there hasn't been a PR yet).

[ayeankit]

@agriyakhetarpal go ahead, currently I working on different issues.

[rtimms]

@agriyakhetarpal sounds great, thanks!

[valentinsulzer]

Re-opening as discussed in #2908