Update theory.rst

[KulaginVladimir]

Proposed changes

This PR attempts to fill the Theory doc page, following #510. @RemDelaporteMathurin, @jhdark what do you think?

Types of changes

What types of changes does your code introduce to FESTIM?

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code refactoring
• Documentation Update (if none of the other choices apply)
• New tests

Checklist

• Black formatted
• Unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (e1d3b36) 98.91% compared to head (c28ea97) 98.91%.
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #664   +/-   ##
=======================================
  Coverage   98.91%   98.91%           
=======================================
  Files          57       57           
  Lines        2128     2128           
=======================================
  Hits         2105     2105           
  Misses         23       23           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[KulaginVladimir]

Another point to discuss concerns splitting of this single file into several separate. Possibly, something like that can be done:

• Theory.rst
  • Bulk physics.rst <- separate file
    • H transport
    • Soret effect
    • Conservation of chemical potential at interfaces
    • Heat transfer
  • Surface physics.rst <- separate file
    • Dirichlet BC
    • Plasma implantation approx (according to the work of @RemDelaporteMathurin)
    • Neumann BC
    • Robin BC

[RemDelaporteMathurin]

@gabriele-ferrero @SamueleMeschini feel free to make suggestions! You can see the compiled documentation by ReadTheDocs in the "checks" ok this PR

[RemDelaporteMathurin]

Another point to discuss concerns splitting of this single file into several separate.

If you really think the file is too long then we can split it in two. However, I would also like to keep the unique page for the Theory (where users can just scroll down instead of navigating to other pages).

• Plasma implantation approx

Yes we need to detail this approximation in the documentation too.

[KulaginVladimir]

If you really think the file is too long then we can split it in two. However, I would also like to keep the unique page for the Theory (where users can just scroll down instead of navigating to other pages).

One page is good

Yes we need to detail this approximation in the documentation too.

Ok

[RemDelaporteMathurin]

If we have a lot of references, is it worth using a proper bibliography management system like this?

[RemDelaporteMathurin]

I noticed we never define what's an Arrhenius law. Maybe we can add something

[KulaginVladimir]

@RemDelaporteMathurin, possibly, we can add here something about the Arrhenius form, namely:

The diffusivity is usually assumed to follow the Arrhenius law of temperature [Reference?]: $D(T)=D_0e^{-\frac{E_d}{kT}}$, where $D_0$ is the diffusivity prefactor, $E_d$ - diffusion activation energy, $k$ - the Boltzmann constant, $T$ - temperature.

[RemDelaporteMathurin]

we could have something more general since it applies not only to the diffusivity but also to trapping rates, solubilities....

[KulaginVladimir]

Therefore, a separate subsection somewhere? The first mention is in the Heat transfer section.

[KulaginVladimir]

Possibly, this paper is appropriate for a reference. Original works of Arrhenius are in deutish as I see

[RemDelaporteMathurin]

Yes maybe a separate subsection, no need for a reference

[KulaginVladimir]

@RemDelaporteMathurin, I made an attempt

[RemDelaporteMathurin]

Really nice work getting the bibliography to work @KulaginVladimir !! It's perfect!

I noticed the ToC (Table of Contents) has been flushed at the bottom of the page

It is supposed to be at the top right

I'll investigate this but I suspect it's somehow linked to the bibliography.
EDIT: maybe it's due to the size of the image... does this disappear if you reduce the size of the image using the width flag?

[RemDelaporteMathurin]

Maybe we don't need the abstracts here

[KulaginVladimir]

To note, local build of docs works fine

[RemDelaporteMathurin]

@KulaginVladimir I still see the same behaviour in the ReadTheDocs compiled docs... do you see it too? https://festim--664.org.readthedocs.build/en/664/theory.html

[KulaginVladimir]

@RemDelaporteMathurin

@KulaginVladimir I still see the same behaviour in the ReadTheDocs compiled docs... do you see it too? https://festim--664.org.readthedocs.build/en/664/theory.html

Yes, unfortunately, I see it. By local doc build, I meant the html files that I build locally before submitting commits.

[RemDelaporteMathurin]

I've openened an issue executablebooks/sphinx-book-theme#792 to track the bibliography problem

[RemDelaporteMathurin]

This is awesome @KulaginVladimir and had been needed for a very long time!

We'll also need this change in the fenicsx branch btw (without the conservation of chemical potential since it'll be handled differently).

We couldn't get rid of the bug of the ToC but it seems that once sphinx7 is supported by sphinx-book-theme then this will be fixed.

In the meantime, would you mind opening an issue here to remind us to have a look at this in a little while?