[willzyba]

I'm find my self doing more and more customisation of OpenFOAM 2.3x and I'm gradually figuring things out, however every time I open a file I can't help but wonder where the in-code documentation has gone.

Surely the original authors would have documented what they were doing, even odd hints about the logic of the structure and why it was done one way over another. If nothing else but to help them in a future release/revision.

I do appreciate I'm a mere mortal looking at code from the Gods. But even the more basic coding standard say you should document it.

So I'm left assuming that there must be a version of OpenFOAM somewhere that does has documentation, but when they release it to the masses they delete all comments and paste in the copyright notices. If this is the case, then can I get a copy of the documented code, or is that propitiatory?

[mohsen cheraghi]

Originally Posted by willzyba

I'm find my self doing more and more customisation of OpenFOAM 2.3x and I'm gradually figuring things out, however every time I open a file I can't help but wonder where the in-code documentation has gone.

Surely the original authors would have documented what they were doing, even odd hints about the logic of the structure and why it was done one way over another. If nothing else but to help them in a future release/revision.

I do appreciate I'm a mere mortal looking at code from the Gods. But even the more basic coding standard say you should document it.

So I'm left assuming that there must be a version of OpenFOAM somewhere that does has documentation, but when they release it to the masses they delete all comments and paste in the copyright notices. If this is the case, then can I get a copy of the documented code, or is that propitiatory?

Hi, I am also looking for such documentation. But, there is not, unfortunately. This is the nature of open source codes

[mturcios777]

Have you looked at the Doxygen documentation? A lot of the comments you are looking for will be there. The most up to date version is always at:

http://www.openfoam.org/docs/cpp

[willzyba]

yes the DOxygen documentation is a good start, which explains some bits in great detail, but most bits not at all. DOxygen also has a great ability to pick up variable names of functions and class members, and it would be great to see this in the documentation you mentioned.

To give an example. We've integrated Lagrangian Particle Tracking within WaveFoam. Now works like a dream if anyone wants the code. The actual modifications were not particular hard, though I am boggled by the code structure: seems as though there is twice as much code as needed - I digress....

So I come across these lines in solidParticle.C:

            scalar rhop = td.cloud().rhop();
            scalar magUr = mag(Uc - U_);
            
            scalar ReFunc = 1.0;
            scalar Re = magUr*d_/nuc;

            if (Re > 0.01)
            {
                ReFunc += 0.15*pow(Re, 0.687);
            }

            scalar Dc = (24.0*nuc/d_)*ReFunc*(3.0/4.0)*(rhoc/(d_*rhop));

            U_ = (U_ + dt*(Dc*Uc + (1.0 - rhoc/rhop)*td.g()))/(1.0 + dt*Dc);

This is clearly a calculation of Drag and the acceleration on my particles. But where has this formulation come from? Turns out there are half a dozen similar, but subtly different, solutions. So it would be great if the author had commented on what standard or even website they had copied it from. And I'll bet the author probably even has a paper on this - but I don't even know who they are..

As I do start to document bits, where should this be posted. And how might we encourage all users of OpenFOAM to start document any bits they do understand. I'm sure some base work by all would accelerate the development of OpenFOAM. And we're happy to do our part.

[wyldckat]

Greetings to all!

@Will:

1. Feel free to contribute to the (unofficial) OpenFOAM Wiki: http://openfoamwiki.net - In your case, the following locations might be of interest:
   • Somewhat old page with instructions on how to contribute: http://openfoamwiki.net/index.php/Main_Policy
   • Contributed examples documentation: http://openfoamwiki.net/index.php/Main_ContribExamples
   • Extending the documentation of OpenFOAM's source code: http://openfoamwiki.net/index.php/OpenFOAM_guide
2. May it be open or closed source, most source code is usually always lacking the comments we need, either because the programmer had to fix/implement a feature in a hurry, or because it was a lengthy implementation.
3. OpenFOAM's source code is sometimes more documented than you might expect, but also only explained in the location where you might be least expecting. Many times you need to track back to the original class from which the current class is deriving from, in order to see the comment that details what this class is all about. Searching for methods with an identical name usually helps to check what the methods are.
4. Beyond this, OpenFOAM is open-source, but its evolution can only proceed based on sponsorship, usually from those commercially interested in having new features implemented. This makes sense, at least from the point of view of giving focus to the main development team, as well as a means to live and survive in the real-not-very-free-nor-open-source-world we live in
   This to say that those who hire commercial support and/or attend their training sessions, can more easily get the answers they're looking for.
5. In addition, if not all classes/solvers are properly documented, its most likely because the sponsorship didn't fully cover the implementation of said class/solver, or because it comes from very old code which is already detailed in one of the original thesis for its development. For example, if you look at all of the RAS turbulence models implemented in OpenFOAM, some of them are barely documented, while others are fully documented.
6. Keep in mind that even though things might be free or completely open, Time is always unrelenting in the way it keeps going forward .
7. As for "solidParticle.C": the programmers/authors could very likely be using a hybrid formulation based on more than one paper, based on the validation results they've achieved. The respective validation+support documentation might not have been published in a paper and/or might only have been published for the original sponsor.
8. Another hypothesis is that the paper(s) is/are only indicated in the release notes for one of the versions. If I'm not mistaken, solid particle formulation is mentioned a few times in some of the release notes... try using in Google:
   

   site:www.openfoam.org release notes

Best regards,
Bruno

[mohsen cheraghi]

Originally Posted by mturcios777

Have you looked at the Doxygen documentation? A lot of the comments you are looking for will be there. The most up to date version is always at:

http://www.openfoam.org/docs/cpp

Thank you, I did not care about this documentation. But, It seems to be very useful

[willzyba]

wyldckat, thanks for the detailed suggestions.

OpenFoamWiki seems to be a great starting point. Clearly needs a lot of work. As we document all the major changes we make on our own wiki, and it not a major step to upload to openfoamwiki also. I'll put up what we've learnt on LPT.

Will.