How the documentation is organised#
The documentation of pyfe3d is written in four cumulative levels, each
with its own place, so that a reader, or a tool, can go from what a
function does to why it does it without the levels repeating each other.
Level |
Where |
Content |
|---|---|---|
1, functional |
docstrings of the modules, classes, functions and methods, except
their |
what each resource does: a one-line summary, an extended summary
(what, not why), |
2, theory |
the |
the theory that each resource implements, local to it: the governing equations in the notation of the code, the assumptions and limits of validity, the meaning of each parameter in that context, the algorithm, and the published sources |
3, overview |
the pages of this documentation, user guide and usage examples |
how the pieces of level 2 fit together: the workflow of an analysis, the conventions shared by the modules, the choice of element, with links to the API instead of repeating level 2 |
4, worked examples |
the notebooks of the Tutorials |
complete analyses, mostly benchmarks reproduced from the literature, with stored outputs |
The API pages render levels 1 and 2 together. To find the theory of a
resource, read the Notes of its docstring; to find how a method fits in
an analysis, read the pages of level 3, starting from Overview and workflow.
The tests#
The tests in tests/ are part of level 1 and are also usage examples,
see Repository structure. Each test states in its docstring what it
verifies and against what:
a published value, a table or an equation of the literature, cited with its location, e.g. the buckling load of a simply supported plate of Leissa (1969), Eq. (10.46);
a closed-form solution written in the test, with its source;
a property that holds for any input, e.g. the invariance of a buckling load under a rigid rotation of the model, the rank of an element matrix, or a patch test.
When a finite element result is compared with the literature, the
tolerance is that of the discretisation, measured by refining the mesh
and stated in the docstring, or one of the grades of MacNeal and Harder
(1985), and not a value fitted to the output of the code. When the
literature is matched only on a mesh too expensive for a test, the
docstring records the runs of the same test with a larger refinement
that match it, and the test compares its coarse mesh with the value that
the same test gave on that mesh, with a tolerance for round-off only,
keeping a check against the literature within a grade.