nek5000/nekdoc

Documentation for Nek5000

Nek5000 Documentation

This is the repository of the Nek5000 documentation written using the Sphinx documentation framework.

How to build

• 'make html' builds the user documentation as a set of interlinked HTML and image files. The top-level webpage is build/html/index.html. Supporting HTML and image files are also in the build directory.

Note: This requires the Sphinx and sphinx_rtd_theme Python packages. Both are available from the Python Package Index.

How to contribute

Please create a fork of the repository and make pull/merge requests. Keep in mind that the number of binary files should be kept minimal. The Makefile should be adapted to any special build requirements.

New issues or requests are welcome to be reported.

How to publish on GitHub Pages

To update the GitHub Page, a contributor must have write permissions to the main NekDoc repository.
The GitHub Page should not contain any edits that are newer than the master branch of the main repository.

Workflow:

1. Checkout the latest master
2. run make gh-pages

nekdoc's Issues

Quickstart has typo

cp -r ../examples/eddy .

and anywhere should have examples replaced by short_tests

Problem-Size File (SIZE) section is outdated

Description holds for legacy SIZE only.

Boundary Conditions are incomplete

• add missing BC
• add what they impose (e.g. SYM: dut/dn=0 and un=0)
• add what to specify in userbc
• reconsider current location (mesh generation is quite misleading)

http://nek5000.github.io/NekDoc/geometry.html#boundary-conditions

Add conjugate heat transfer tutorial

Setting up a conjugate heat transfer problem is not documented.

Governing equations in Introduction should go to Appendix or Theory section

Revise History Points sections to reflect current

Currently, history points are only discussed in section 3.3- (Geometry and Parameters file .rea) which doesn't seem reflective of how users currently use history points.

I'll try and provide two pull requests to add a reference to an additional section on how to use history points through user files.

default values for par file

A list of the default values used by Nek for any key not specified in the .par file would be useful, e.g. if the 'dealiasing' key is omitted from the [GENERAL] section of the .par file, it gets set to 'yes'.

format of time derivatives

format of temporal derivatives in the introduction section is inconsistent.

Description of error codes

Would you consider documenting the numeric values and meanings of error codes produced by Nek? When I'm using libnek5000 from other apps, it would be helpful if I could process the errors intelligently.

Add PPLIST documentation?

There doesn't seem to be any description of the PPLIST options, e.g. BGQ, MPIIO, etc. I started some here, but maybe it belongs in the doc as well or instead?

Revitalization of Prenek/Pretex Documentation

There is a potential benefit towards revitalizing the older documentation from the following sources:

1. http://www.mcs.anl.gov/~fischer/Nek5000/nekmanual.pdf
2. http://www.mcs.anl.gov/~oanam/old_page/index.php/Prenek

Considering it could play a large role for simple shapes to complex meshes with a lot of extruded but connected regions, I think it may be a topic worth putting effort into.

Thoughts?

Add tutorials

In this chapter we shall describe in detail the process of setup, simulation and post-processing for some Nek5000 test cases, with the principal aim of introducing a user to the basic procedures of running Nek5000

Auto-deploy GitHub Pages from Travis?

Any interest in auto-deploying the GitHub pages from Travis? I think it's possible:
https://docs.travis-ci.com/user/deployment/pages/

Update overview of all internally used parameters

Add neknek tutorial

Explicit filtering and HPFRT is not described anywhere

A description of how the filter works would be very helpful

Memory Requirement section is wrong

Actually memory footprint depends on various things like:

• OS
• Compiler
• Nek settings (lx1, nelt, nelgt, dealising, residual projection, time integration order, mesh motion, …)
• MPI (depends strongly on the number of ranks)

Current estimate of 3200 bytes/gridpt ignores memory allocation by MPI and arrays scaling with lelg or lp. A more accurate estimate would be:

bytes per rank := 3200*(nelgt * lx1**3)/np + 8*nelgt + MPI(np)

different tables for COMMON keys

Both Tables 3 and 7 in the par file description document different [COMMON] keys. They should be combined into a single table.

Description of AMG Workflow is outdated

Workflow outlined in https://nek5000.github.io/NekDoc/large_scale.html#amg-solver is outdated.

Automatically update gh-pages after merge

It would be nice to automatically update gh-pages after new changes are merged into "master". What's the best mechanism for doing this?

Though there is a makefile target for updating gh-pages ("make gh-pages"), I'm not sure if we can do this with Travis. Whoever/whatever runs "make gh-pages" needs permissions to update the repository, and I'm not sure how we can manage those permissions with Travis.

Document NEKUSE variables

Time stepping scheme is not discussed (Both default and Characteristic Time Stepping)

The time stepping scheme for both the default 2nd and 3rd order BDF/EXTk and the characteristic time stepping (OIFS) are not mentioned or explained in the manual. This is important for users to understand the available time stepping schemes and how to properly implement them. There is a few mentions of OIFS in the appendix but it is not discussed in terms of usage or differences from BDF/EXTk.

Some references that could help:
http://fischerp.cs.illinois.edu/cs598/docs/notes_time1b.pdf - Theory
https://www.mcs.anl.gov/~fischer/nek5000/fischer_nek5000_dec2010.pdf - Basic implementation discussion
http://www.mcs.anl.gov/~fischer/Nek5000/primer.pdf - OIFS usage

Add description of available timers

Add a software design document (chapter)

Grid-to-Grid interpolation section is outdated

g2gi() was replaced by gfldr() including a new workflow.

How to use CVODE as a solver for scalars is not documented

5.1 Large scale simulations - Question is "asked" but following information is not related.

In the large_scale.tex tex file for the manual, the following section of discussion is found.

Size related issues Large simulations require a high number of nodes and thus a high number of variables. So far Nek5000 supports by default 4 byte integers, however the node numbering for big meshes may exceed this size and 8 byte integers may be needed. How is this done?

If more than 9 passive scalars are needed

Exiting Nek5000 while a batch job in being executed should be done not using "qdel" but echo -1 > ioinfo.

MAKENEK The shell script makenek is designed to assist the compilation process of NEK5000. The script will create a makefile based on the user settings section in makenek. The GNU gmake utility is used to build NEK5000. Available configurations options:

Can the appropriate persons such as @fischer1, @stgeke, or @oanaoana add some information regarding this question and submit a pull request?

Thanks,

Lane

description of map/ma2 files is missing

Add a list of commonly used variables

Updating "Quick Start"

Section 2, "Quick Start", should be updated with instructions for the Git repo. I intend to keep the instructions for the SVN repo, as well.

Creation of a citations section of all user created journal, conference, and other papers

This would be set up such that users could add their citations of their publications through pull requests.

Add an overview of all examples and what they demonstrate

Description of makenek options is outdated

https://nek5000.github.io/NekDoc/large_scale.html#makenek

Document use of ioinfo

Wiki as the primary source of documentation

I suggest to use the build-in wiki on GitHub as the primary source of documentation. The wiki is a git repo in itself, so there is no need for an extra NekDoc repo. To do this we need to sort out two things: (1) How to embed Latex (2) How to convert multiple wiki pages into one combined document (as a pdf) for print. I am not an expert on this but it looks doable to me.

Add instruciton how to setup an env for developers

The quickstart documentation mentions an examples/ directory that doesn't seem to exist in the Nek5000 repo anymore (I gather those moved to the NekExamples repo). Along the same lines, the Running your first simulation doesn't work because there's no examples directory.

Add FAQs

• How do I compute an integral over a boundary patch?

• How do I launch a parallel run?

• How do I run the examples?

• How to convert a mesh to Nek5000

• Why it is important to non-dimensionalize my case?

• How do I obtain values of variables at a point?

• How do I choose solver tolerances?

• My simulation diverges. What should I do?

• What post-processing options are available?

• ...

numsteps key

key for number of time steps is incorrect in .par file description, should be 'numsteps', not 'numstep'.

Redundant information Quickstart section and README

https://nek5000.github.io/NekDoc/quickstart.html
https://github.com/Nek5000/Nek5000/blob/master/README.md

Change structure for better readability

Travis tests for PR

Upon a PR, we should compile the PDF and HTML to check for compilation errors.

Update ns_eqns to fix Re and Fr numbers - Pull #16 - Approved but not implemented

The pull request to fix some of the issues identified in Pull #16 were "approved" but not implemented.

Description of re2 file format is missing

We borrowed some part of the old legacy rea but this to be update to be compiliant with the current re2 format.

Source-level Docs for Developer's Guide?

What's the outlook for source-level documentation in the proposed developers guild (see Issue #65)?

If you're interested in bringing back the Doxygen, it seems we can still integrate it in the current Sphynx docs (see this FAQ). I still have an ancient Doxyfile that simply generates the descriptions of the code structure (with links and whatnot). Might be a good start. However, since Nek doesn't have much Doxygen-formatted in-source comments, the resulting doc is still pretty bare. I've heard rumors that KTH made some more progress with Doxygen (@pschlatt1, @adampep)?

If you're interested in a pure Sphynx solution, then we can either document in-source or out-of-source with Sphinx domains.

IMO, the main thing to consider is whether you want in-source or out-of-source docs. I believe Doxygen would be better for in-source whereas Sphinx domains would be better for out-of-source.

Use explicit variable declarations in tutorials

parameter 2 incorrect in Case Setup File section

parameter 2 is listed as kinematic viscosity (nu) in the table at the end of "Routines in .usr File" section. It should be molecular viscosity (mu). It is correct elsewhere in the documentation.

Description of .par file parameters is missing

Quickstart has typo

cp -r ../examples/eddy .

and anywhere should have examples replaced by short_tests

Spectral Interpolation Tool section is outdated

API has changed, see hemi example

Suggestions for tutorial

Being a Nek newbie, I'm reading through the tutorial and finding that it leaves many questions unanswered that would seem relevant to a new user. For example, in the Modify mesh and apply mass flux section that shows an example of usrdat2, it's not at all obvious what variables are global, what variables are implicit local variables, and what variables might have been defined by the include statements. Adding declarations for local variables would clear things up a bit. It would also help to put a link there to the Case Files section on usrdat2.

In the Initial & boundary conditions section, the same problem regarding implicit local vs global vs included variables is present. The formal arguments of the useric are not mentioned in text or in the example source code, so a reader would just have to make assumptions about both the type and purpose. After digging around the source code, I see that ux, uy, and uz are declared in a common block and eventually copied to the vx or bx, etc. arrays. There are a few issues in my mind:

• ux, uy, and uz are not described anywhere, even the appendix
• The units of ux, uy, and uz are not specified. If they are non-dimensional, that should probably be mentioned somewhere (the units for other quantities like xm1 and ym1 are also not mentioned)
• I don't see bx, by, bz mentioned in the appendix even though useric could affect them. Is it something a user should be aware of?

Also, useric doesn't appear under the list of subroutines in the Case Files section.