Contribute to GROMACS Project

Developers discussions
1

GROMACS version: Latest
GROMACS modification: No

I am a student enrolled in the Simulation Software Engineering course, at the University of Stuttgart, and am eager to contribute to the GROMACS project as part of the coursework requirements. I aim to make a meaningful contribution, which could include developing a new feature, enhancing documentation, creating a tutorial, improving packaging, or addressing a bugfix. Please let me know if there are specific areas where my efforts would be most beneficial to the project. You can find more information about the course on this link.

2

Welome! Please, keep an eye on the Developers discussions - GROMACS forums part of the forum. A good start for such a project would be to join one of our biweekly Wednesday meetings. However, the one this week is cancelled and then there is a break during Christmas. So, the next one is not until Jan 8. I hope that is not too late for your plans.

There is a list of topics that are considered good for new GROMACS developers:
Issues Ā· GROMACS / GROMACS Ā· GitLab. But keep in mind that some of those may still be a bit complex.

Donā€™t hesitate to ask for guidance.

3

By the way, Developer Guide - GROMACS 2024.4 documentation might be a good resource, if you havenā€™t read it already.

4

@Jafarkhani: I added you to the gmx_developers group here so that you can post your questions in the ā€œDeveloper Discussionsā€ section. You can, of course, ask questions specific to issues directly on GitLab.

5

Thank you for your guidance, Magnus! Attending one of the Wednesday meetings sounds greatā€”Iā€™ll join the next one. In the meantime, Iā€™ll review the issues and choose one that aligns well with the project and is feasible to complete within a month. Additionally, Iā€™ll work through the available tutorials to better understand the theory and how GROMACS operates!

6

Thank you for adding me to the Developersā€™ Discussion Forum. Iā€™ll reach out if I encounter any issues.

7

Hello
I have an issue regarding running and inspecting current warnings of doxygen in Gromacs. When I run cmake . on folder docs/doxygen I get an error as:

CMake Error at CMakeLists.txt:34 (include):
  include could not find requested file:

    gmxCustomCommandUtilities

CMake Error at CMakeLists.txt:35 (include):
  include could not find requested file:

    gmxOptionUtilities

CMake Error at CMakeLists.txt:51 (gmx_dependent_option):
  Unknown CMake command "gmx_dependent_option".

What is the problem? I am a little bit beginner regarding cmake and doxygen and I would appreciate it if you could help me step by step:

  • build doxygen content with current version 1.8.5
  • update version
  • View warnings

I want to see how to reproduce warnings that was mentioned in issue #4690, mentioned by Vedran Miletić for versions 1.10.0 or 1.9.4

Regards

8

You need run CMake from the top-level directory. You cannot build only the documentation (at least, thatā€™s not intended).

The high level description is in our documentation. For specific example of how the documentation is built, check our CI scripts; thatā€™s what I personally do whenever I need to build docs locally.

The CI uses a Docker image, which you can build using our helper scripts (in admin/containers):

python3 scripted_gmx_docker_builds.py --ubuntu 24.04 --llvm 19 --doxygen --mpi openmpi --venvs 3.9.13 3.12.5 | docker build -t registry.gitlab.com/gromacs/gromacs/ci-ubuntu-24.04-llvm-19-docs -

You can either build the documentation in Docker or directly on Linux, the build steps are just the same. But later, you would need to update the helper script to use the newer Doxygen version. That would either be step 2 if you run in Docker. If you run without docker, update the Doxygen on your system however you prefer. The part of the helper script would still need to be updated when you submit the final MR.

P.S.: I also moved this topic to ā€œDeveloper Discussionsā€.

P.P.S.: Tagging @vedran, since he looked into this in more depth.

9

I run Doxygen without the containers, installed system-wide. After the configuration with GMX_DEVELOPER_BUILD set to ON and build, I run the command cmake --build builddir --target doxygen-all, which gives the results described in the issue.

I hope this helps.

1 Like
10

Thanks, I tested it and now it works, even without docker.
Unfortunately, there is a bug on the latest version of MacOS which prevents docker from running!
I also had to build with -DGMX_OPENMP=OFF since it is not compatible with my Mac chip.
Thanks again for your quick response.

11

Thatā€™s ok, OpenMP is not needed for docs.

If you for some reason want OpenMP later, you can follow our Installation guide to see how to get OpenMP working on macOS; or install libomp and gcc via Homebrew and use those. But again, you donā€™t need OpenMP unless youā€™re actually running GROMACS :)

12

Hi
First thank you again for responding to my problems so quickly, I really appreciate it.
I have an issue regarding make doxygen-full command. When I carefully read the CMakeLists.txt file in docs/doxygen, I found out we also run some Python scripts like graphbuilder.py etc. These files generates error during cmake. Mostly complaining about
class "XXXX" was already added. Maybe you have two entities with the same name value
I assume these scripts were written by the dev team, but I am not sure that these errors relates to the new doxygen version (I am running with the latest version 1.13.2) or not. When I turn off USE_PYTHON_SCRIPTS config, doxygen builds successfully.
My question is that is it OK to continue without running those scripts?

13 
    # Add targets for generating the dependency graphs; they are necessary for
    # the full and lib variants of the documentation.
    if (USE_PYTHON_SCRIPTS)

We want to keep the dependency graphs, so they would need to be fixed eventually.

But you can first proceed without them, deal with whatever other issues arise, and only when everything else works go on with enabling the scripts. Or perhaps replace them with some other solution.

14

Hi

I just exported doxygen warnings into a file, and here is a summary of warnings:

Doxygen Warnings
Doxygen Warnings824Ɨ400 43.3 KB

  • %76 of warnings indicate that nearly 1700 members are not documented. Resolving these issues is impossible for me since I need some background in the code/theory.

  • %17 of warnings are categorized by ignoring command, which refers to non-existing group referrals. For example, we mention \ingroup module_applied_forces, but in fact, this group does not exist. Here is the list of missing groups:

module_applied_forces
module_compat
module_fft
module_fileio
module_gmxlib_nonbonded
module_preprocessing
module_gpu_utils
module_hardware
module_math
module_mdlib
mdspan
module_mdtypes
module_mimic
module_pbcutil
module_pulling
module_topology

These warnings could be resolved by finding their existing counterparts.

Other warnings could also be resolved. For example, does not return anything category is for those methods which are void, but we indicated a return type for them.
Here you can download the report.txt (507.9 KB) file

Also, I noticed something strange in the HTML output. We have so many anonymous_namespace namespaces in our final HTML file. Is there a way to find a solution to resolve it?

15

Have you checked how many are with the current Doxygen? We indeed have a bunch of those, but most are ignored by our CI script, and so are of no concern.

Defining new groups would be a better solution. It does not look like those are typos, more like we started adding things to a group without first declaring the group to exist. \defgroup + some broad description should do it.

We have quite a few anonymous namespace ā‰ˆ static function ā‰ˆ functions not used outside the file. Perhaps their rendering in Doxygen can be improved, but I donā€™t think itā€™s a high priority thing.

16

Hi
I just tested building multiple versions of doxygen on GROMACS, and I just found out that switching from version 1.12 to 1.13 (the latest release is 1.13.2) produces an error:

Generating include dependency graphs for dot
Scanning source tree...
Reading source files...
Reading Doxygen XML files...
Traceback (most recent call last):
  File "/gromacs/docs/doxygen/graphbuilder.py", line 584, in <module>
    main()
  File "/gromacs/docs/doxygen/graphbuilder.py", line 559, in main
    tree.load_xml(only_files=True)
  File "/gromacs/docs/doxygen/gmxtree.py", line 846, in load_xml
    self._docset = xml.DocumentationSet(xmldir, self._reporter)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/gromacs/docs/doxygen/doxygenxml.py", line 1188, in __init__
    member.add_parent_compound(compound)
  File "/gromacs/docs/doxygen/doxygenxml.py", line 415, in add_parent_compound
    self._class is None
AssertionError: Class "gmx::IsSerializableEnum" was already added. Maybe you have two entities with the same name value
make[3]: *** [docs/doxygen/CMakeFiles/dep-graphs-dot.dir/build.make:76: docs/doxygen/dep-graphs-dot-timestamp.txt] Error 1
make[2]: *** [CMakeFiles/Makefile2:7582: docs/doxygen/CMakeFiles/dep-graphs-dot.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:7697: docs/doxygen/CMakeFiles/doxygen-full.dir/rule] Error 2
make: *** [Makefile:2565: doxygen-full] Error 2

I am wondering which version of doxygen you prefer? If the latest version is intended, then I have to trace the error. If 1.12 is also acceptable, then I can continue with other parts.

Also, I added two commits to resolve invalid return types
0001-Resolve-invalid-return-types.txt (20.1 KB)
and missing groups
0002-Resolve-missing-ingroup-names.txt (11.5 KB)
to my fork.

17

Latest version is better, but 1.12 is ok (itā€™s what Fedora 41 has and is already newer than what Debian and Ubuntu ship). If youā€™re stuck with this script, no need to block all progress because of it.

I would suggest getting things to work with 1.12 and making an MR.