Suggestions for tutorial

[paulromano]

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.

[stgeke]

I agree. It's difficult for us to be a newbie ;) Are you willing to post a pull request?

…

-----Original message-----

From:Paul Romano ***@***.***> Sent: Thursday 15th March 2018 15:40 To: Nek5000/NekDoc ***@***.***> Cc: Subscribed ***@***.***> Subject: [Nek5000/NekDoc] Suggestions for tutorial (#67) 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 <http://nek5000.github.io/NekDoc/tutorials.html#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 <http://nek5000.github.io/NekDoc/user_files.html#usrdat2>. In the Initial & boundary conditions <http://nek5000.github.io/NekDoc/tutorials.html#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. � You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#67>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ARumfzXZVjmKcv-QlLe8odTDkuJWTiTbks5ten0cgaJpZM4SsRWh>.

[paulromano]

For at least some of the issues, yes, I'd be happy to submit a pull request. Some of the questions I legitimately don't know the answer to out of my own stupidity (like what units are used, and the difference between vx and bx).

[stgeke]

• It doesn't make sense to document the units as they are either non-dimensional or user specific
• Added Document NEKUSE variables #78 to explaining variables like ux, bx, ...
• Added Use explicit variable declarations in tutorials #79 to make local (user) /common-block (internal) variables more transparent
• useric is in the case file description