inconsistent multithread (-x option) behavior

[jkmgeo]

Hi, all. Thanks for your hard work with GMT, and apologies in advance if this issue is improperly tagged, etc.! (I'm filing this as a bug because a more realistic label like "non-urgent improvement" isn't available.)

---

Description of the problem

GMT6 (compiled with OpenMP/GLIB support) appears to exhibit inconsistent multi-thread behavior. Specifically, when interpolating via surface with flag -Vi, GMT reports:

surface [INFORMATION]: Enable all available threads (up to <MY_CPU's_MAX_THREADS>),

even when the -x option is not set. However, when following a call to surface with one to grdfilter (also with flag -Vi) in the same script, GMT does not report the number of enabled threads, and lists output sequentially, i.e.,

grdfilter [INFORMATION]: Processing output line 1
grdfilter [INFORMATION]: Processing output line 2
...

That said, when explicitly passing the -x option to grdfilter, output lines are reported to be processed non-sequentially, and Task Manager shows greater CPU utilization by GMT. This would suggest that surface is parallelized by default, but grdfilter is not.

The documentation added to my confusion:

• surface: the 6.5.0 web documentation makes no mention of parallelization or -x, but the -x option is included when calling gmt surface --help from the command line.

• grdfilter: the 6.5.0 web docs and help both include a brief description of the -x flag.

• In all cases where present, the -x docstring is from gmt/doc/rst/source/explain_core.rst

  • doesn't clarify whether multi-threaded behavior is enabled by default (even if on a per-module basis), or if -x must be set explicitly to enable multi-threading
  • does sound only like a way to override gmt.conf thread count settings, specifically to lower the number of threads used.

Other notes:

• I only dug into surface and grdfilter, so can't say whether this issue extends to other modules.
• As far as I can tell, this issue doesn't actually yield any incorrect results, just slower processing times of calls to grdfilter.
• There seem to be recent (proposed? implemented?) changes to -x (e.g., #8300) to possibly be mindful of.

"Fix" ideas

• parallelize grdfilter (and any other affected modules) by default when supported?
• revise the explain_core documentation?

---

System information

• Operating system: Win11 (23H2)
• GMT version (gmt --version): GMT 6.5.0 (installed via miniconda and run in VSCode via Git Bash)

[welcome]

👋 Thanks for opening your first issue here! Please make sure you filled out the template with as much detail as possible. We appreciate that you took the time to contribute!

Please make sure you read our Contributing Guide and abide by our Code of Conduct.

[joa-quim]

OK, I've worked a bit on this and ended up with #8523 One of the reasons for the inconsistency is that while most parallelized codes use OpenMP, grdfilter uses gthreads and followed a different development path. I now make all cores by default in #8523. This still leaves out the gmt & grdgravmag3d modules in the potential supplement because the tests were showing conflicting results between the runs in my machine and those of the CI tests.

The issue with surface showing the -x option on the online help was an error. There was an attempt to OpenMP 'ize surface but, if I still remember, there were some small differences that were never resolved and that code still lives in the repository but is not in use. Maybe it was from there that the -x option was advertised but it was never really implemented. I removed it #8523.

Also clarified the -x in explain_core.rst.

Let's hope that the PR is good. For the moment Mac seems to be still resisting.

[joa-quim]

Addressed bu #8523