Ideas for documentation

[kinnala]

After finishing with hex-support, I'd really wish to improve the tutorials and user documentation. I'm open for any ideas, but here are some:

• Write more thorough introductions to the examples and parse them onto a web page for easy access.
• Choose a couple of interesting examples and promote them on README.md as 'highlights'.

Any obvious ideas that I'm missing?

[kinnala]

I'm working on Read the Docs implementation where descriptions written in reStructuredText are parsed from example docstring.

[gdmcbain]

Yes, I envisage a few different categories of examples.

• Simple introductory ones,
  • solving standard partial differential equations
  • on meshes simple enough to generate in code in a few lines
  • demonstrating basic kinds of boundary condition (Dirichlet, Neumann, Robin, integral constraints)
  • basic kinds of analysis (steady, unsteady, modal)
  • Together these in sequence form an introduction covering most of the intrinsic functionality
  • Maybe one of these in the README but the rest don't need to be in the package, could be in readthedocs, scikit-fem.github.io, &c.
• More detailed didactic ones
  • Demonstrating technical details of scikit-fem or finite elements (preprocessing, discretization, solution, postprocessing)
  • Forming subsequent chapters of user's guide
  • Doesn't need to be in package
• A gallery
  • More involved specialized problems
  • Not intended to be read in sequence
  • Possibly involving less common equations that require some scientific background or mathematical derivation
  • Can involve secondary packages which are not to be regarded as dependencies of scikit-fem
  • Demonstrate that scikit-fem plays nicely with a large number of other packages
  • Can be big (both large individual examples and many in number), because the gallery should not be part of the package
  • Can involve complicated geometry or mesh
  • Some might have colourful pictures or animations
  • Should be reasonably easily reproducible though, e.g. contain full source code
• Regression test cases
  • Need to be part of the package, though not necessarily installed by default
  • Should only involve the essential dependencies
  • Don't have to be the same as introductory examples, but can be related
  • Probably not the same as the gallery as these tests should run reasonably quickly and don't have to be showy or interesting
  • Might use method of manufactured solutions, which isn't great for introductory examples or gallery
  • This is the suite of tests that has to be passed in continuous integration
• Convergence and performance test cases
  • These tend to have to be bigger than the tests of the previous category to be useful
  • I find convergence tests a very good way of uncovering bugs
  • Although there are reasons to avoid premature optimization, one doesn't want to introduce changes that degrade performance too much, and ultimately performance is of interest in finite element analysis

[kinnala]

You have good ideas and clearly have considered these aspects carefully.

I started something akin to the first point at https://scikit-fem.readthedocs.io/en/latest/.

It basically just parses ex01.py and its docstring (even the first example is not ready yet, but published it just as a demonstration). I like the approach where the documentation of an example is located in the same file so you are more likely to update the documentation when you make modifications to the example code.

I suppose the file docs/index.rst can be easily extended to contain the second type of examples you propose.

There are some regression and convergence tests under /tests but they are poorly documented. You think these and similar tests could be included in the user guide as well?

[gdmcbain]

https://scikit-fem.readthedocs.io/en/latest/ looks very good. Very good start.

The source code in ./docs and ./examples/ex01.py is clear too. I was initially puzzled by the switch from Markdown to reStructuredText and having the docstring at the end of the file instead of the beginning but see that those make sense in the context of readthedocs. And yes, it's great to have the text and code for an example in the same place.

I suppose that at some point index.rst gets split into multiple pages or a tree. I think this looks like (modified from pytoolz/doc/source/index.rst)

Contents
^^^^^^^^

.. toctree::
   :maxdepth: 2

   installation.rst
   tutorial.rst
   gallery.rst
   methodology.rst
   convergence.rst
   performance.rst
   api.rst

Another chapter to add is that last one, the API, the reference manual. I think this gets generated automatically as in pytoolz/doc/source/api.rst which shows up as api.html.

No, probably regression tests are too boring to include in RTD. Some convergence tests might be like that too, but quite a lot of the finite element literature is about rates of convergence so I imagine there is room for that kind of thing in the manual; ditto for stability (e.g. of combinations of elements in mixed methods) and performance (e.g. scaling, direct v. iterative solution, preconditioning).

[kinnala]

Currently the user doc contains three documented examples and preliminary api doc. @gdmcbain in your envisionings, would the current examples correspond to tutorials or gallery?

At some point I plan adding in depth explanation of Mesh classes, and also how assembly works on a technical level.

I also hope to add a more advanced nonlinear elasticity example at some point, and fluid mechanics example.

[gdmcbain]

I'd say that the current examples at

• https://scikit-fem.readthedocs.io/en/latest/examples.html

are tutorials, yes, because they're fairly minimal in terms of only introducing a few new concepts at a time, and because each of these is explained as it's introduced.

[gdmcbain]

For fluid mechanics, one could already count ex01.py and ex12.py as these give the fully developed laminar velocity in ducts of square and circular section, respectively.

To follow, I was thinking:

• potential free surface, e.g. a steadily rotating open bowl
• sloshing, again potential, either harmonic response or modal analysis
• maybe potential flow over a wing section, using superposition of two solutions to get the one satisfying the Kutta–Joukowsky condition
• two-dimensional Stokes flow via stream-function, since this is analogous to the Kirchhoff plate of ex02
• two-dimensional Stokes flow via velocity-pressure using Taylor–Hood elements
• advection–diffusion, maybe the Graetz problem
• two-dimensional Navier–Stokes, via Newton iteration, maybe backward-facing step
• ...

Three dimensional incompressible flow is going to be challenging.

[kinnala]

I have some knowhow in mixed methods for Stokes flow so I might start with that. My knowledge is, however, fairly mathematical and any help in choosing a proper example problem would be appreciated. Currently I'd probably just solve the lid driven cavity flow (2D and 3D) due to simple geometry.

[gdmcbain]

Great. Yes, everyone does the lid-driven cavity. Personally I think that that's unfortunate because it's singular at the corners at the ends of the lid. I'd have preferred flow driven by a body force f = (0, x), particularly in a circle or ellipse since that has a simple closed form solution at zero Reynolds number. However, it's probably better to defer to convention and go with the lid-driven cavity. Oh, the other class I thought to add to that list was Darcy's groundwater equation. Envoyé depuis ProtonMail mobile

…

-------- Message d'origine -------- On 24 sept. 2018 à 17:30, Tom Gustafsson a écrit : I have some knowhow in mixed methods for Stokes flow so I might start with that. My knowledge is, however, fairly mathematical and any help in choosing a proper example problem would be appreciated. I'd probably just solve the lid driven cavity flow (2D and 3D) due to simple geometry. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread. {"api_version":"1.0","publisher":{"api_key":"05dde50f1d1a384dd78767c55493e4bb","name":"GitHub"},"entity":{"external_key":"github/kinnala/scikit-fem","title":"kinnala/scikit-fem","subtitle":"GitHub repository","main_image_url":"https://assets-cdn.github.com/images/email/message_cards/header.png","avatar_image_url":"https://assets-cdn.github.com/images/email/message_cards/avatar.png","action":{"name":"Open in GitHub","url":"https://github.com/kinnala/scikit-fem"}},"updates":{"snippets":[{"icon":"PERSON","message":"@kinnala in #31: I have some knowhow in mixed methods for Stokes flow so I might start with that. My knowledge is, however, fairly mathematical and any help in choosing a proper example problem would be appreciated. I'd probably just solve the lid driven cavity flow (2D and 3D) due to simple geometry. "}],"action":{"name":"View Issue","url":"#31 (comment)"}}} [ { "@context": "http://schema.org", "@type": "EmailMessage", "potentialAction": { "@type": "ViewAction", "target": "#31 (comment)", "url": "#31 (comment)", "name": "View Issue" }, "description": "View this Issue on GitHub", "publisher": { "@type": "Organization", "name": "GitHub", "url": "https://github.com" } }, { "@type": "MessageCard", "@context": "http://schema.org/extensions", "hideOriginalBody": "false", "originator": "AF6C5A86-E920-430C-9C59-A73278B5EFEB", "title": "Re: [kinnala/scikit-fem] Ideas for documentation (#31)", "sections": [ { "text": "", "activityTitle": "**Tom Gustafsson**", "activityImage": "https://assets-cdn.github.com/images/email/message_cards/avatar.png", "activitySubtitle": "@kinnala", "facts": [ ] } ], "potentialAction": [ { "name": "Add a comment", "@type": "ActionCard", "inputs": [ { "isMultiLine": true, "@type": "TextInput", "id": "IssueComment", "isRequired": false } ], "actions": [ { "name": "Comment", "@type": "HttpPOST", "target": "https://api.github.com", "body": "{\n\"commandName\": \"IssueComment\",\n\"repositoryFullName\": \"kinnala/scikit-fem\",\n\"issueId\": 31,\n\"IssueComment\": \"{{IssueComment.value}}\"\n}" } ] }, { "name": "Close issue", "@type": "HttpPOST", "target": "https://api.github.com", "body": "{\n\"commandName\": \"IssueClose\",\n\"repositoryFullName\": \"kinnala/scikit-fem\",\n\"issueId\": 31\n}" }, { "targets": [ { "os": "default", "uri": "#31 (comment)" } ], "@type": "OpenUri", "name": "View on GitHub" }, { "name": "Unsubscribe", "@type": "HttpPOST", "target": "https://api.github.com", "body": "{\n\"commandName\": \"MuteNotification\",\n\"threadId\": 367662500\n}" } ], "themeColor": "26292E" } ]

[kinnala]

Archiving this. Will definitely use some ideas from here in the future.

[gdmcbain]

I thought of another category of documentation: comparison with other finite element packages. One of the first questions of each new user must be why scikit-fem rather than ——, or for which uses might scikit-fem be a good choice.

For me, the ease of installation was key: I was able to distribute scikit-fem without the end-user even really knowing: I just included it in install_requires in the setup.py. The Pythonic purity all the way down to SciPy was another big plus.

Perhaps submitting an entry to https://github.com/kostyfisik/FEA-compare or similar would be worthwhile.

[gdmcbain]

A related category is rosettacode-style examples done in multiple codes. These might have a number of benefits:

• as quick-start tutorials or reference cards for those more familiar with another code
• illuminate relative advantages and disadvantages of the different syntaxes (e.g. Renamed: Better form arguments and docstrings. #101)

Following discussions at recent conferences, I have cause to look at FEniCS again and thought that for my own learning I might translate the examples from Solving PDEs in Python—The FEniCS Tutorial into scikit-fem. Do you think that these would be worth sharing somewhere? Perhaps in a simple github repo.

[kinnala]

Yeah, I think this is a good idea. In principle, I'd enjoy having everything under https://kinnala.github.io/scikit-fem-docs/learning.html but I'm not sure if I have enough time to pack everything in properly. My first goal is to add all the examples under docs/examples but it takes some work to transform everything so that they look and feel consistent.

If you'd like to use Sphinx/RST to write the examples, then incorporating them later would be easy. Otherwise, we can always include an external link whatever format you choose.

[gdmcbain]

I'm not sure whether it will be worth including many translations of the FEniCS examples in the main scikit-fem documentation. There will be a fair bit of overlap with the existing examples (Poisson, heat, elasticity, Stokes), and I wasn't intending on rewriting any of the explanatory text, figuring that the original by Langtangen & Logg still stands—the idea is that one could read that and then look at the FEniCS and scikit-fem Python scripts side-by-side and see fairly easily how the same thing is accomplished in each system.

For the moment, I'll post the drafts in a new repo, https://github.com/gdmcbain/fenics-tuto-in-skfem. Once they're there, we can decide whether they're worth keeping and what to do with them.

If this exercise does lead to any interestingly new scikit-fem examples, I'll probably change them a fair bit to be more idiomatically scikit-fem and then will write them up in reStructuredText for use here. (Possibilities: splitting methods for transient Navier–Stokes, use of SymPy or similar for nonlinearity, passing linear algebraic systems off to PETSc or similar instead of SciPy, rereading a saved transient velocity simulation for use in a subsequent transient advection–diffusion, …)