The Firedrake Manual

[JDBetteridge]

A PR for the long awaited Firedrake Manual.

Please take the time to review the changes to both the website and the generated PDF. If you find errors, please report these below. Even better, correct them and open a new PR against this PR. The easiest way to view the documentation in this PR is to checkout this branch and firedrake-update --documentation-dependencies (see instructions here). The pdf can be generated by running make latexpdf.

Nobody has been excluded deliberately in this manual, if you think your name/institution/work/documentation/demo/funding should be included and hasn't, please update your details or start a discussion below. If you are unsure, please message in slack or start a github discussion to ask.

If you want to update your details please edit /docs/source/team.ini appropriately.

If you want to update funding, please edit /docs/source/funding.rst appropriately.

If you want to add a new paper for the publications page, please open a fresh PR against master.

[JDBetteridge]

Firedrake_draft1.pdf

[wence-]

Some minor initial comments:

• I think the authors should have affiliations, since this is long-lived, affiliations might change. The way PETSc deal with this is they maintain the full affiliation list (approximately) for each author with their current affiliation last (e.g. I would be Imperial College London, Durham University, NVIDIA). I guess this is perhaps more cogent for PETSc due to their lab affiliations.

• I should probably update the team page wrt Durham.

• the list of funding page is quite out of date.

[JDBetteridge]

Some minor initial comments:

• I think the authors should have affiliations, since this is long-lived, affiliations might change. The way PETSc deal with this is they maintain the full affiliation list (approximately) for each author with their current affiliation last (e.g. I would be Imperial College London, Durham University, NVIDIA). I guess this is perhaps more cogent for PETSc due to their lab affiliations.

• I should probably update the team page wrt Durham.

• the list of funding page is quite out of date.

I like first bullet, this seems to be a good way of keeping track of where everyone is. Do you have a personal webpage or equivalent we should be linking to?

Regarding the second two, I agree, this info is quite out of date. We'll discuss this at the next Firedrake meeting at the latest. What is currently in the PDF is just the material that exists on the website at present.

[wence-]

I like first bullet, this seems to be a good way of keeping track of where everyone is.

Do you have a personal webpage or equivalent we should be linking to?

I don't, but that's separate (let me update my details in a separate PR).

[connorjward]

I found that the line

A python script version of this demo can be found here.

in the immersed fem demo has a broken link apart from on the website. What is the best approach to linking to the Python scripts we autogenerate from the RST? I'm happy to do the fix, just not sure what I should be doing.

More generally I've found that quite a few of the links in these demos do not work.

[wence-]

I found that the line

A python script version of this demo can be found here.

in the immersed fem demo has a broken link apart from on the website. What is the best approach to linking to the Python scripts we autogenerate from the RST? I'm happy to do the fix, just not sure what I should be doing.

I think in the PDF manual, that line should either link to the equivalent website one, or else be removed, or replaced with some other text that points to the right place. There's no point linking to a PDF-formatted version of the python code (it's just as hard to copy). Having said that, I think PDF does support embedding files, see for example https://www.ctan.org/pkg/embedfile, but that's probably more work than necessary?

[connorjward]

I found that the line

A python script version of this demo can be found here.

in the immersed fem demo has a broken link apart from on the website. What is the best approach to linking to the Python scripts we autogenerate from the RST? I'm happy to do the fix, just not sure what I should be doing.

More generally I've found that quite a few of the links in these demos do not work.

Hopefully fixed in #2747

Also I've found another issue. In, for example, the DG advection demo in the manual the "References" section at the bottom is empty (but the references are visible on the website).

[ReubenHill]

6fbe5fa pahahahaha

[ReubenHill]

What's going on with the test failures? They look like actual failures rather than a crashed worker or ram running out

[JDBetteridge]

What's going on with the test failures? They look like actual failures rather than a crashed worker or ram running out

They are coming from upstream. I'd quite like to get this merged and open a new PR for edits. This way all the link validation can be put into master and we won't have to keep rebasing

[ReubenHill]

What's going on with the test failures? They look like actual failures rather than a crashed worker or ram running out

They are coming from upstream. I'd quite like to get this merged and open a new PR for edits. This way all the link validation can be put into master and we won't have to keep rebasing

Well are we happy to merge without waiting for all tests to pass then? If none of the example tests are failing then I'd be happy with that

[JDBetteridge]

Done