View Issue Details

IDProjectCategoryView StatusLast Update
0002311OpenFOAMBugpublic2016-11-08 23:08
Reporterwyldckat Assigned Tochris  
Status closedResolutionno change required 
Summary0002311: Request for FAQ and/or General Troubleshooting page at OpenFOAM Foundation's website
DescriptionThis is something I can easily do on and have done for some situations already, but since the occurrence rate on some details will potentially be popping up more frequently here on the bug tracker, it feels like we are getting to the point where we should have a FAQ or General Troubleshooting page on the OpenFOAM Foundation website or the User Guide or the Code Documentation page.

Examples to start with for populating the new page:

1. Installation issues on the Ubuntu pages have been duplicated a few times already on the website, e.g.:

2. Aliases for common commands (cd, grep, sed), as well as "GREP_OPTIONS" and "CDPATH", can break the expected work-flow of OpenFOAM's shell scripts.

  - One recent example for aliases hampering OpenFOAM's scripts was reported in #2296 and related backslashes were striped from "Allrun/Allclean" scripts sometime ago in #2077;

  - "GREP_OPTIONS" didn't reach the bug tracker:

  - "CDPATH" (mentioned in #2310) can break the recent feature in "etc/bashrc" of setting "FOAM_INST_DIR" based on the sourcing path, which uses "cd" to go into the folder related to where "bashrc" is reported to come from. The reason why it can break it is explained in detail here: - but the reason is simple: it can output the text of the same path twice.

  I did figure out a way on how we could suspend alias expanding on Bash, which would be just a matter of prefixing and suffixing onto "etc/bashrc":

    # Ensure alias expansion is disabled while this script is being sourced
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    shopt -u expand_aliases


    # Reset to default alias expansion
    # ~~~~~~~~~~~~~~~~~~~~~~~~~

  Problem is that "shopt" doesn't exist in Dash (common with Ubuntu) which means that an additional would be needed, neither a similar alternative for C-shell (csh), which would allow to avoid having to riddle OpenFOAM's scripts with backslashes for several/all commands.

3. Built-in reader in ParaView/VTK for OpenFOAM cases has issues handling special boundary conditions. This is something that has been pointed out in a few bug reports already as not being OpenFOAM's fault (unless 'evolution' is a deemed a flaw), therefore this is another entry that should go up onto said new page.

4. Section "Notes" in "ThirdParty-*/", which although is in the right place already, could be referenced in the new page as well, just in case people don't read the file and only search/report on the Foundation website.

There is also the possibility where we could have said page in ".org" or ".md" format at "OpenFOAM-*/docs", so that it could more easily be contributed to by the community and automatically have it on the Code Documentation page, e.g.:

If this last one is acceptable/preferable, I could take care of it, although I'm not yet fully familiar with the .org format.
TagsNo tags attached.



2016-10-29 22:34

updater   ~0007073

Remembered about another one:

5. User friendliness is something that OpenFOAM can only go so far into doing. Hand-holding is something that is usually left to GUIs (and user support/training requests), therefore there are several situations where the complaints (or absence of them) that OpenFOAM makes can be a bit cryptic. Examples:

  - Issue #2252, where foamToVTK gave a cryptic error message when using "-fields".

  - Issue #2198, where not having the OpenFOAM environment loaded leads to messages like "Can't open /wmake/scripts/AllwmakeParseArguments"

  - Issue #1473, where the following feature was: "Added InfoSwitches::writeOptionalEntries which enables the writing of optional keywords and values which are not present in the dictionary." - which is useful for users to learn to pay better attention at what they are writing incorrectly in the dictionary files... albeit it's still as troublesome to sift through, but still... the feature is there.


2016-10-29 22:59

updater   ~0007075

Remembered about another detail, regarding entry no. 2, specifically issue #2077: Using backslashes for escaping commands on Allrun/Allclean scripts was possibly also used for shell functions that were overriding command commands, e.g. a function for "rm" may be useful for ensuring it's not used incorrectly and/or to move files to a 'trash' folder.


2016-11-07 20:57

manager   ~0007125

I think we are hitting the law of diminishing returns here. It surely expends more energy to maintain an entry about aliasing cd, sed or grep (which is done at the user's own risk), and for readers to read and ignore it... than the benefit provided to 1 person in 5,000 who aliases cd, sed or grep - and happens to find the entry amongst a sea of (mis)information about OpenFOAM on the Internet.

I would prefer wes put our effort into eliminating problems and encourage use of the latest version of OpenFOAM.


2016-11-08 23:07

updater   ~0007128

Hi Chris, many thanks for the feedback!

Very good point. I was so focused on making sure all issues are addressed, even those that are "not fixable" in OpenFOAM (i.e. not OpenFOAM's fault), that I forgot the ratio of affected users.

I'll close this issue as "no change required", but I'll still document some of these issues in the FAQ at the unofficial wiki, even though these issues are fairly rare to occur.

Issue History

Date Modified Username Field Change
2016-10-29 22:20 wyldckat New Issue
2016-10-29 22:34 wyldckat Note Added: 0007073
2016-10-29 22:59 wyldckat Note Added: 0007075
2016-11-07 20:57 chris Note Added: 0007125
2016-11-08 23:07 wyldckat Note Added: 0007128
2016-11-08 23:08 wyldckat Assigned To => chris
2016-11-08 23:08 wyldckat Status new => closed
2016-11-08 23:08 wyldckat Resolution open => no change required