[tcarrigan]

Hello OpenFOAMers,

I've been using OpenFOAM for a month now for a wide variety of CFD cases and have been a little frustrated to find no general purpose guide on how to set up and successfully run a case. Of course there is the OpenFOAM user guide available on OpenCFDs website with tutorials and descriptions of pretty much everything you would want to know, but it doesn't seem to touch on how to set up a real world test case. Forums are also another great place to get information specific to the case you are trying to set up, and simply going to google and searching for reports and presentations does help and can find excellent sources for information.

However, wouldn't it be nice if a rather simple document existed that showed users how to set up a case from start to finish without digging into the math or programming. Something that easily describes the files that are required in the case directory to get it running. Something that shows how to implement a turbulence model with and without the use of a wall function. Something that demonstrated several key applications like simpleFoam, simpleSRFFoam, MRFSimpleFoam, turbFoam, icoFoam, etc. from start to finish. Even showed how to do simple postprocessing using the sample tool, or how to plot residuals, monitor drag force, plot results using gnuplot, etc. And use real cases like turbomachinery, aircraft, cars, and others to describe the use of these tools.

I'm just wondering if a document like this would help those out like me who seem lost at the very beginning trying to figure out what is needed to run a case, or just need to use OpenFOAM for a specific application but don't want to spend time digging around for an answer. I'm thinking that after some more time familiarizing myself with OpenFOAM I could eventually write something like this and make it available to all those who may benefit from it.

Let me know if a document like this would be of value to you.

[val46]

I'm also pretty new to OF. I started to read the User Manual on the OF website and got familiar with the workflow because of the tutorials.
But you are absolutely right. When you set up your own case you will get little help except from this forum.
The thing is most of the community members are using OF for research purpose only (correct me if I'm wrong here). Thats why the big trouble starts when your case is a real "industry problem".

So I'm pretty sure any detailed documentation about specific problems will be appreciated.

[tcarrigan]

Yeah, I've noticed that OF is used a lot for research. The idea I had in mind was something for people who work in industry or even academia, but want to just use OF as a tool to solve a problem. Thanks for reply.

[Linse]

Hello to both of you!

I am quite new at using OpenFOAM myself and just beginning to cut my teeth at that. While I am one of the people using (well, soon I hope) that Code for research, I also would highly appreciate some "Keep it simple - simply use it" documentation.
About the danger of using a program without knowing the basic background of it I needn't say anything I guess.

The problem concerning documentation seems to be that it is unwanted and discouraged by the holder of the rights at the software, OpenCFD Ltd.
At least that is the impression I get from one of the threads on this forum (some searching for "docu" should be able to find it), as some good guys already had tried to set up a documentation project but were told by the lawers of OpenCFD to stop that, as that would have been seen as infringement of the copyright.

Probably the only way to deal with that problem is to make heavy use of this forum and of the WIKI for OpenFOAM.
We will see, if another way comes to light sometime...

In case there was somebody else to set up such a thing, I would be absolutely willing in matters of contributing some basic instructions, perhaps even testcases...

Read you around and have fun,
Bernhard

[msrinath80]

Originally Posted by Linse

Hello to both of you!

The problem concerning documentation seems to be that it is unwanted and discouraged by the holder of the rights at the software, OpenCFD Ltd.
At least that is the impression I get from one of the threads on this forum (some searching for "docu" should be able to find it), as some good guys already had tried to set up a documentation project but were told by the lawers of OpenCFD to stop that, as that would have been seen as infringement of the copyright.

Bernhard

Where, just where did anyone from OpenCFD ever say that? I searched for "docu" and did not find anything relevant. Please post the link so we can read that.

PS: For very new users please note that in OpenFOAM there is no point and click handholding or jump straight onto the bandwagon without understanding the numerics/physics here. There is no fancy GUI with "default" settings that you can use indiscriminately. I for one, totally adore this project. Simply because I learnt so much more about CFD and numerics in one year than I did by "clicking" around in Fluent for 3 whole years. The more time I spent understanding OpenFOAM the more productive my work was.

That said, if you put in the effort and make a sincere attempt at understanding how things work, the developer folks who parse this forum are more than willing to help. The biggest problem I see is a good chunk of the folks who come here want answers and they want it now! Expectations of smooth learning curves are very unrealistic. It does take time and it is totally worth it!

[maddalena]

Originally Posted by msrinath80

Where, just where did anyone from OpenCFD ever say that? I searched for "docu" and did not find anything relevant. Please post the link so we can read that.

here you are: http://www.cfd-online.com/Forums/ope...shut-down.html.
There are not much more to say about that...

mad

[Linse]

Yep, that was exactly the thread I was talking about, Mad. Thanks for posting the link!

At this point just to make myself understood correctly:

I guess I really will be able to adore OF as soon as I understand it. But the problem is: In my opinion it takes too much time to understand it! Time that could be minimized by better documentation.


Here it goes off-topic til the end!

Just as an example: I do not know what all the entries/numbers in the typical "thermophysicalProperties"-file mean. For example it took me a complete day about finding out where the temperature limits for the calculations are set. The major of the remaining entries in there still just is bogus to me. But I did not find real information about that in the User Guide. U-175 (Version 1.6) does give some information about the models that exist. But other than the janaf-model, none are explained more in detail. In case I really want to make use of the capabilities of the settings, I would need more information on WHAT one is about to change.

Unfortunately also the different models used for the solvers are not really given inside the code. If there was one mentioning of the publication in the comment the code relates to, everything would be fine. The user guide gives pretty few information about such things (if it has to be in there is another question), neither do the tutorials I digged in myself.

You are absolutely true, the physics and the discretization have to be understood in order to use a code properly! But I think this already is at the highest non-annoying level if you use the text-mode method for changing your cases. Simply because you learn about the structure of everything in there.

And another point: The people doing the programming of OpenFOAM and everything somehow related did a hell of a job! Nobody (and at very least not me) will deny that!

But keeping a project like that from being documented without giving the possibility for retaining good documentation just is a blow to the users that might well fire back. If the support would be capable to tell me the necessary things, that would be costly but acceptable. But as I asked for the origin of one model, I was not told that this would be in the paid support thing - I was told it would be documented in the very file. It was not, and neither did the other files I looked through contain the origin of the models.
If I had another, better-documented choice with the same abilities for refinement of the code, I immediately would move away from OpenFOAM. Just because it costs to much time to document it myself. And I read of plenty users that do have the same opinion.

Documentation may be kept on a high niveau for making people understand what they do and get them interested - but it has to exist and be of help!

[marupio]

Originally Posted by Linse

The problem concerning documentation seems to be that it is unwanted and discouraged by the holder of the rights at the software, OpenCFD Ltd.

@Bernhard - I think you are right. OpenCFD runs for-profit training sessions, so producing this documentation would be hurting their bottom line.

The documentation that is really missing is the Programmer's Guide. Not an auto-generated dOxygen, but an actual human-written guide giving the real purpose for each object and its function.

I've been working on exactly that - a programmer's guide for OpenFOAM, and have several dozen offline articles on my personal wiki. I've been slowly transferring them over to the wiki. They are located here:

http://openfoamwiki.net/index.php/Ca...OpenFOAM_guide

I haven't announced this, or made it "official" because I still need to put together a front page, and submission guides. But you guys can have a look and see if it's what you're looking for. The articles currently range from extensive:

http://openfoamwiki.net/index.php/Op...es_in_OpenFOAM

to snippets:

http://openfoamwiki.net/index.php/Op...uide/Transient

Share and enjoy!

EDIT: Corrected the link and added sample articles.

[msrinath80]

Thanks to both of you. I wasn't in touch with OpenFOAM for quite some time. Should have at least monitored the user-forums. Anyways, all that needs to be done is to then focus on the OpenFOAM extensions project. Hrv has always been the most accomodating and I'm sure he understands how useful documentation resources can be.

[alberto]

The problem of lack of documentation has been largely discussed, and I believe it is key to the success of the project.

However, we users should be realistic. OpenFOAM is an open source project many are using, and many are taking advantage of without it giving anything back, with some, very evident, exception.

In the current situation, if you want to learn using OpenFOAM you either take the time of studying it by yourself, which is indeed a long process, or you attend one of the training courses, which are offered at a fraction of the cost you would pay for a commercial code and for the training to learn how to use it, which is something industrial customers of commercial software usually do. In this way you also support the development of the code, and you help ensuring its future.

I say this because in these years I helped a quite large number of people both here on the forum and in private, spending a good amount of time. I did it for free, for personal interest, refusing only when the request was evidently from someone with commercial purposes (they should simply pay for a consultancy service!), and it has been probably a better learning experience for me than for them.

However I too often have been disappointed by the complete lack of interest in sharing the help received with others, with excuses like confidentiality (clearly not true).
It all comes to the attitude of who asks for help, and then goes away, without returning the favour. And it is the reason why the wiki is not exactly complete and in a good shape.

About the -extend project, it is a very good initiative, but I do not think it resolves the only problem that blocked the documentation project, which is the name of the project itself (OpenFOAM-extend is clearly a derivative of the trademark OpenFOAM(r)).
In the past I pushed quite strongly in the past to simply try to convince a name change was necessary, but it did not happen and I do not surely plan to start over that kind of discussion. Probably keeping the trademark in the name of the -extend initiative is convenient, since OpenFOAM is established already, but it still in violation of a policy, which might or might not be applied, and which costs really nothing to respect to avoid any further tension.

Best,

[alberto]

Originally Posted by Linse

Hello to both of you!

I am quite new at using OpenFOAM myself and just beginning to cut my teeth at that. While I am one of the people using (well, soon I hope) that Code for research, I also would highly appreciate some "Keep it simple - simply use it" documentation.

I absolutely agree with this. :-)

The problem concerning documentation seems to be that it is unwanted and discouraged by the holder of the rights at the software, OpenCFD Ltd.
At least that is the impression I get from one of the threads on this forum (some searching for "docu" should be able to find it), as some good guys already had tried to set up a documentation project but were told by the lawers of OpenCFD to stop that, as that would have been seen as infringement of the copyright.

There is some confusion about this. The documentation project was stopped for only one reason: the name, not a copyright infringement. The website was called initially openfoam-documention, then foam-documentation, and OpenCFD believed this was in conflict with their trademark policy. In other words, it was a trademark infringement.

You probably noticed I was very involved in that discussion. Seeing it after some time, and in a more relaxed way, I see mistakes on both sides. I still find OpenCFD(R) reaction not proportionate (even if legally justified, probably), but I also think a solution could have been found inside the community.

The problem is that the community seemed unable to have an open discussion on the topic, and still is unable to discuss openly about almost everything which is not a technical problem of the software, neglecting that organizational aspects are as important. There are workshops, meetings, SIG's, but nothing is going on openly and online, which would make cooperation much easier, as it happens in a large number of open source projects.

Best,

[tcarrigan]

Originally Posted by Linse

I am quite new at using OpenFOAM myself and just beginning to cut my teeth at that. While I am one of the people using (well, soon I hope) that Code for research, I also would highly appreciate some "Keep it simple - simply use it" documentation.

This was my idea. I'd like to come up with some form of documentation and put it somewhere where people can have access to it that simply describes OF and how it can be used to tackle a certain class of problems. Like I said earlier, I don't want to go into great detail about the under workings of the project as much as how to use it as a tool to solve a problem.

I know OF doesn't have a fancy UI or anything of the sort, and I understand that most people using OF for research enjoy this project simply because it leads to a higher level of understand of not only OF, but CFD in general.

What I am proposing is not a way to cut corners, but a way to get to work quickly and not spend a day trying to find out how to implement a wall function for the kepsilon turbulence model, when in fact wall functions are coded in all the RANS models. Stuff like this can be documented fairly well, and this is what I would like to accomplish.

In most cases you have to know what you are doing, you have to understand the basics of CFD to run a case, even if the solver has a fancy point and click UI. It's those people, people like myself, who would benefit from a simple document that keeps them from stumbling around for a day to answer a simple question.

[holger_marschall]

Originally Posted by tcarrigan

I'd like to come up with some form of documentation and put it somewhere where people can have access to it that simply describes OF and how it can be used to tackle a certain class of problems.

Hi Travis,

thanks for your initiative on this. IMO, a "Quick getting-started guide" on OpenFOAM(R) would be really appreciated by many users.

Originally Posted by tcarrigan

What I am proposing is not a way to cut corners, but a way to get to work quickly and not spend a day trying to find out how to implement a wall function for the kepsilon turbulence model, when in fact wall functions are coded in all the RANS models. Stuff like this can be documented fairly well, and this is what I would like to accomplish.

... this goes more into modeling. I think it's best to put it into the Wiki. What do you think?

best regards,

[marupio]

Hi guys, if you want to contribute to the unofficial programmer's guide, we're doing something different on the Wiki. Instead of using one of the prefixes (contrib, howto, snip, etc...), we're using sub pages. The main page is "OpenFOAM guide", and any articles fall under this... e.g.

http://openfoamwiki.net/index.php/OpenFOAM_guide/tmp

http://openfoamwiki.net/index.php/Op...ide/H_operator

And so on...

[tcarrigan]

Holger,

Thanks for your reply. Yeah, I think the wiki is a great place for something like this.