How to use the Documentation / Docs

[Tazarus]

Hi Everyone,

I am struggling to find key information about what options/variables/parameters exist and how to use them when using PyBaMM.

Typically a scour of the documentation on a function is enough to know what parameter options there are, how to use them, and what to expect from doing so.

However, I am finding the Docs for PyBaMM often seem to be missing what I would consider crucial information. I presume this is likely due to a lack of knowledge on my part, or my ignorance of how the documentation is intended to be used,

Some examples include:

1. From the DFN model page https://pybamm.readthedocs.io/en/latest/source/models/lithium_ion/dfn.html
   

This tells me I can pass options to the model, but not what options there are, or what they do. There are no links to this information either.

2. From simulation.plot()
   https://pybamm.readthedocs.io/en/latest/source/simulation.html
   
   There is no information about what output variables can be passed to the method, or that by passing nested lists you can specify which variables you want on which axis.

3. Detailed parameter information regarding the parameters listed by: pybamm.ParameterValues(chemistry=chemistry)
   Are there more detailed descriptions of the parameters in the docs? If so, where can I find them? While many of the parameters have descriptive names and included units that are very helpful, more detailed explanations, particularly of parameters not commonly used in experimental work, would be very helpful! My supervisor, Jeff Dahn, is an expert in the field, and when I came to him to start working on parameter sets for modelling some of our cells in lab, he asked for more information about the "Inner SEI ____" parameters, and despite over an hour of digging through docs I have been unable to find anything more detailed then the name and the units.

While most (if not all) of this information can be found by going over examples from the workbooks. But I was wondering if the same information is indeed in the docs, but I'm not looking in the right places.

Thanks,
-Christian

[rtimms]

Thanks for the feedback. There are definitely places in the docs that can be improved, so it's useful to highlight these. In answer to these specific questions

1. The model options are documented here. We should link to this class in the other model class' docs.
2. You can pass any of the variables in your model (you can do model.variables to see all the variables or search by doing e.g. model.variables.search("electrolyte"). There is a basic plotting notebook too. We should add some examples to the docstring and explain that you can nest lists.
3. The parameters all have references attached. You can take a look in this folder and click through to find README files. The SEI models are probably the most poorly documented ones we have. The EC reaction limited model follows from the article by Yang et al 2017 while the other models are taken from Scott Marquis' thesis. These references provide a more detailed description of the models and parameters.