Feature: C-API for Geometry Analytic

[jmark]

Describe your changes here:

Also added an 11th example to geometry examples to test the C API.

All these boxes must be checked by the reviewers before merging the pull request:

As a reviewer please read through all the code lines and make sure that the code is fully understood, bug free, well-documented and well-structured.

General

• The reviewer executed the new code features at least once and checked the results manually

• The code follows the t8code coding guidelines

• New source/header files are properly added to the Makefiles

• The code is well documented

• All function declarations, structs/classes and their members have a proper doxygen documentation

• All new algorithms and data structures are sufficiently optimal in terms of memory and runtime (If this should be merged, but there is still potential for optimization, create a new issue)

Tests

• The code is covered in an existing or new test case using Google Test

Github action

• The code compiles without warning in debugging and release mode, with and without MPI (this should be executed automatically in a github action)

• All tests pass (in various configurations, this should be executed automatically in a github action)

  If the Pull request introduces code that is not covered by the github action (for example coupling with a new library):

  • Should this use case be added to the github action?
  • If not, does the specific use case compile and all tests pass (check manually)

Scripts and Wiki

• If a new directory with source-files is added, it must be covered by the script/find_all_source_files.scp to check the indentation of these files.
• If this PR introduces a new feature, it must be covered in an example/tutorial and a Wiki article.

Licence

• The author added a BSD statement to doc/ (or already has one)

[jfussbro]

The changes look good and the example works fine 👍

[jfussbro]

One last small change :)

[sandro-elsweijer]

Why move all the functions from the hxx header to the new h header? All the other geometries just provide a new and destroy function in their c interface. I think we should keep everything in the hxx header, since we want to move to cpp anyway.

[jmark]

Why move all the functions from the hxx header to the new h header? All the other geometries just provide a new and destroy function in their c interface. I think we should keep everything in the hxx header, since we want to move to cpp anyway.

@sandro-elsweijer .hpp header files cannot be included in .c files. In order to use the geometry analytical interface from C the signatures for the callbacks must be present in the .h file.

[sandro-elsweijer]

Why move all the functions from the hxx header to the new h header? All the other geometries just provide a new and destroy function in their c interface. I think we should keep everything in the hxx header, since we want to move to cpp anyway.

@sandro-elsweijer .hpp header files cannot be included in .c files. In order to use the geometry analytical interface from C the signatures for the callbacks must be present in the .h file.

@jmark I understand your problem here. But it bugs me, that the cpp interface would be removed even though we want to have an explicit cpp interface. Maybe we can discuss defining these functions twice in the next developer meeting

[jmark]

@jmark I understand your problem here. But it bugs me, that the cpp interface would be removed even though we want to have an explicit cpp interface. Maybe we can discuss defining these functions twice in the next developer meeting

If you want a real C++ API for this then I suggest to offer a geometry analytic base class from which you derive and implement the analytical evaluate and Jacobian member functions. The actual evaluate and Jacobian function (wrapping around the analytical callbacks) should be finalized in the analytical geometry base class, of course.

BTW: The C++ interface is not removed. The .h header file is included in the .hpp header. Technically, nothing changed from the C++ perspective.

[sandro-elsweijer]

@jmark I understand your problem here. But it bugs me, that the cpp interface would be removed even though we want to have an explicit cpp interface. Maybe we can discuss defining these functions twice in the next developer meeting

If you want a real C++ API for this then I suggest to offer a geometry analytic base class from which you derive and implement the analytical evaluate and Jacobian member functions. The actual evaluate and Jacobian function (wrapping around the analytical callbacks) should be finalized in the analytical geometry base class, of course.

BTW: The C++ interface is not removed. The .h header file is included in the .hpp header. Technically, nothing changed from the C++ perspective.

@jmark Then let's keep this in mind for our cpp interface t8code week. Do you mind writing an issue for that so that we do not forget it?

[jmark]

@jmark I understand your problem here. But it bugs me, that the cpp interface would be removed even though we want to have an explicit cpp interface. Maybe we can discuss defining these functions twice in the next developer meeting

If you want a real C++ API for this then I suggest to offer a geometry analytic base class from which you derive and implement the analytical evaluate and Jacobian member functions. The actual evaluate and Jacobian function (wrapping around the analytical callbacks) should be finalized in the analytical geometry base class, of course.
BTW: The C++ interface is not removed. The .h header file is included in the .hpp header. Technically, nothing changed from the C++ perspective.

@jmark Then let's keep this in mind for our cpp interface t8code week. Do you mind writing an issue for that so that we do not forget it?

Done. #904

@jfussbro @sandro-elsweijer Anything else to do?

[jfussbro]

Approved! :)

[jmark]

@sandro-elsweijer ?

[jmark]

@sandro-elsweijer ??

[sandro-elsweijer]

Just minor comments

[jmark]

Just minor comments

Thank you very much! Refactored as you suggested.