FEM Workbench Testing - GSoC Proposal

About the development of the FEM module/workbench.

Moderator: bernd

User avatar
Kunda1
Posts: 5949
Joined: Thu Jan 05, 2017 9:03 pm

Re: FEM Workbench Testing - GSoC Proposal

Postby Kunda1 » Thu Jun 20, 2019 9:15 pm

m42kus wrote:
Thu Jun 20, 2019 6:17 pm
I also updated my devlog where you can find more details: https://ceeli.github.io/gsoc
Thanks! BTW, do you mind adding something like: Devlog: https://ceeli.github.io/gsoc/ in to your signature?
m42kus wrote:
Thu Jun 20, 2019 6:17 pm
One thing I did yesterday was to setup a alternative version of FreeCADs doxygen documentation. Imo doxygens default configuration is a bit overloaded so I hacked together a lighter prototype. It only includes documented C++ code and is hosted on github. I did this just so I can keep track of my stuff but maybe you find something worth stealing .
Cool! Doxygen is a beast and we have quite a ways ahead of figuring out how we should document the FC code. Currently it's swiss cheese when it comes to API documentaion generated from within the code and there are mixed feelings about making the source code bloated by generating documentation this way. Maybe your approach can generate some consensus and even a convention around documenting ??? :pray:
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Fri Jun 21, 2019 9:12 am

Kunda1 wrote:
Thu Jun 20, 2019 9:15 pm
Thanks! BTW, do you mind adding something like: Devlog: https://ceeli.github.io/gsoc/ in to your signature?
Good idea, I just added it :)
Kunda1 wrote:
Thu Jun 20, 2019 9:15 pm
Cool! Doxygen is a beast and we have quite a ways ahead of figuring out how we should document the FC code. Currently it's swiss cheese when it comes to API documentaion generated from within the code and there are mixed feelings about making the source code bloated by generating documentation this way. Maybe your approach can generate some consensus and even a convention around documenting ??? :pray:
Yes the documentation is very sparse at the moment. Doxygen supports in code as well as embedding external documentation. Doing everything in the source blows up the code like you said but doing everything external is messy, hard to track and it's tedious to read the code together with the documentation. I think the best way is to combine both approaches. Documentation of members definitely belong in the source code but descriptions with examples and so on of classes, namespaces or modules could be moved out into a separate file.

Like you said the most important (and most challenging) thing is that the approach is consistently used on every part of FreeCAD. I definitely think that source documentation can't be substituted by wiki articles and if done right it's very easy to use (for both developer and user). Because writing tests is not really meaningful without stating what the function is supposed to to I'm going to write a lot of documentation. Lets see how my approach of documenting evolves during GSoC and maybe if it's received well by the community we can take parts or all of it for all of FreeCAD :)
My GSoC Devlog: ceeli.github.io/gsoc
User avatar
Kunda1
Posts: 5949
Joined: Thu Jan 05, 2017 9:03 pm

Re: FEM Workbench Testing - GSoC Proposal

Postby Kunda1 » Fri Jun 21, 2019 11:52 am

m42kus wrote:
Fri Jun 21, 2019 9:12 am
Lets see how my approach of documenting evolves during GSoC and maybe if it's received well by the community we can take parts or all of it for all of FreeCAD :)
I'm looking forward to this! Thank you very much @m42kus :D
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Wed Jun 26, 2019 11:06 pm

This week I wrote more C++ tests and documentation for the C++ module specifically for Fem::Constraint. While doing so I extended the C++ test support library further with useful tools. For details have a look at my devlog or the github repository. While looking through the code a noted a few things that don't affect the working of the workbench directly but are probably worth fixing. I wrote most of those points into notes of the source documentation. In the documentation of Fem::Constraint you find a few of these notes: https://ceeli.github.io/fcdoc/classFem_ ... raint.html.

I'm far from completing all unit tests that should be written for the modules C++ code but despite that I will move on to my next target which are python tests without GUI. The general theme for the next month will be that I try to cover as many different aspects of testing as possible. After that I should have a very good understanding of the requirements and challenges of testing all aspects of a module and I will try to combine everything into a consistent and systematic testing approach. This means of course means that I won't be able devote as much time to each aspect as it deserves but I think that the framework is much more important. I hope that if the framework is good enough we can slowly move to complete test coverage with the help of the whole community :)
My GSoC Devlog: ceeli.github.io/gsoc
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Fri Jun 28, 2019 11:50 am

I fixed a few issues with my code on ubuntu and tested it on Ubuntu 16.04. My testing branch should now compile on those systems without problems. No additional dependencies are required. To execute the tests I wrote just execute the FreeCADTest binary. Be sure to do a recursive clone (with submodules) because I included googletest as a submodule in the 3rdParty folder. I don't know if that is a problem for anyone. The problem is that ubuntu doesn't ship compiled google test libraries. One could use the sources from googletest-dev instead but that would require distribution specific cmake code. Including googletest in the source should work on every platform without modifications. As an alternative to a submodule we could of course just copy the code into the repository...

As of now there is no switch to turn on or off the test compilation. This is certainly on my todo list but doesn't have a high priority for now.
My GSoC Devlog: ceeli.github.io/gsoc
User avatar
kkremitzki
Posts: 1796
Joined: Thu Mar 03, 2016 9:52 pm
Location: Texas

Re: FEM Workbench Testing - GSoC Proposal

Postby kkremitzki » Fri Jun 28, 2019 3:09 pm

From my Debian packaging perspective, vendoring a copy of gtest in our source is fine, so long as there's support to use the system gtest if it's present. In Debian we can filter out unwanted copies of software that's already available in the system.
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Thu Jul 11, 2019 9:36 pm

kkremitzki wrote:
Fri Jun 28, 2019 3:09 pm
From my Debian packaging perspective, vendoring a copy of gtest in our source is fine, so long as there's support to use the system gtest if it's present. In Debian we can filter out unwanted copies of software that's already available in the system.
Hey, I don't know if debian does it differently from ubuntu but for ubuntu the recommended way of using gtest is to include it in the source. The libraries are not even available as binaries in the repositories. Do you have any experience with gtest on debian? If not I can look into it :)

@All There is a lot of new stuff on my devlog btw: https://ceeli.github.io/gsoc/
I'm going to write a summery in here to in the next days :)
My GSoC Devlog: ceeli.github.io/gsoc
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Tue Jul 16, 2019 9:58 pm

Hi, just a quick status update: At the beginning of this month I progressed from writing C++ tests to writing tests for/in python. I wrote lots of documentation and tests for the femtools/femutils.py module. Right now I'm working on testing the solver framework and on a new kind of test that runs simulation and checks the results (not just if there where any errors but also if the results are what we expected e.g. displacement). I created a test support library analog to what I created for C++. You can find all of that in my testing branch: https://github.com/ceeli/FreeCAD_bhb/tree/testing.

I'm also spending a lot of time making my in source documentation appear nicely in sphinx and created a kind of sphinx prototype I'm going to share soon if you are interested. Does anyone know what the most popular opinion is for documenting python code in FreeCAD? Is it doxygen or sphinx? What I'm doing now is using sphinx with readthedocs and I combine in source documentation with pages written only for sphinx. That's of course more work than using only API documentation generation but I believe that the end result is way better. I think there is little harm in using doxygen for C++ and sphinx for python and the benefits outweigh the drawbacks (e.g. consistency).
My GSoC Devlog: ceeli.github.io/gsoc
m42kus
Posts: 159
Joined: Tue Sep 02, 2014 9:41 am

Re: FEM Workbench Testing - GSoC Proposal

Postby m42kus » Fri Jul 26, 2019 9:50 am

Hi, I played around with sphinx and wrote some documentation for the FEM workbench specifically the solver framework. It's not finished but you can have a look at readthedocs: https://freecad-python-api.readthedocs. ... rview.html or https://freecad-python-api.readthedocs. ... tings.html. The other modules are empty, I just inserted them to show how it could look :) My experience is that sphinx works much better with python than doxygen. Doxygen works great for C++ but I found doxygen with python almost unusable. I think that the best approach would be to use doxygen for C++ and sphinx for python. I think that is done to a certain extend already but not very consistent. Honestly I am a little confused about what the current state of documentation is in FreeCAD :P. What do you think about that?
Kunda1 wrote: ping
yorik wrote: ping
Last edited by m42kus on Fri Jul 26, 2019 10:20 am, edited 1 time in total.
My GSoC Devlog: ceeli.github.io/gsoc
Jee-Bee
Posts: 1970
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: FEM Workbench Testing - GSoC Proposal

Postby Jee-Bee » Fri Jul 26, 2019 10:01 am

looks great!