pygmt.grd2xyz: Improve performance by storing output in virtual files

[seisman]

Changes in this PR:

• Refactor the grd2xyz function using the virtualfile_out/virtualfile_to_dataset methods (address Consistent table-like output for PyGMT functions/methods #1318 and Get rid of temporary files from pygmt functions and plotting methods #2730)
• Add type hints to the output_type/outfile parameters and return value
• Remove four tests that are not directly related to grd2xyz (see pygmt.grd2xyz: Improve performance by storing output in virtual files #3097 (comment)).
• Combine the test_grd2xyz and test_grd2xyz_format tests into a single one

Preview: https://pygmt-dev--3097.org.readthedocs.build/en/3097/api/generated/pygmt.grd2xyz.html#pygmt.grd2xyz

[codspeed-hq]

CodSpeed Performance Report

Merging #3097 will degrade performances by 81.76%

_{⚠️ No base runs were found}

_{Falling back to comparing output/grd2xyz (2c5aeb3) with main (0b46aad)}

Summary

❌ 1 regressions
✅ 97 untouched benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

	Benchmark	main	output/grd2xyz	Change
❌	test_grd2xyz	43.1 ms	236.2 ms	-81.76%

[seisman]

The four tests are not directly related to grd2xyz. test_grd2xyz_file_output is already covered by the doctest of the Session.virtualfile_out method. The other three tests will be covered by doctests in PR #3098.

[seisman]

CodSpeed Performance Report

Merging #3097 will degrade performances by 81.22%

⚠️ No base runs were found

Falling back to comparing output/grd2xyz (f423c7d) with main (0b46aad)

Summary

❌ 1 regressions ✅ 97 untouched benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

Benchmark main output/grd2xyz Change
❌ test_grd2xyz 43.1 ms 229.4 ms -81.22%

Run the test locally:

>>> import pygmt
>>> from pygmt.helpers.testing import load_static_earth_relief
>>> grid = load_static_earth_relief()
>>> %timeit pygmt.grd2xyz(grid=grid, output_type="numpy")

In the main branch:

5.06 ms ± 345 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

In this branch:

10 ms ± 185 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

So, for this small test, the new version is much slower, as suggested by the CodeSpeed benchmark report.

For a larger grid data:

>>> import pygmt
>>>  for res in ["01d", "30m", "15m", "10m"]:
...     %timeit pygmt.grd2xyz(grid=f"@earth_relief_{res}_g")
...

In the main branch:

98.4 ms ± 4.77 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
444 ms ± 45.3 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
1.6 s ± 33.9 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
3.67 s ± 129 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

In this branch:

21.8 ms ± 2.98 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
57 ms ± 7.55 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
143 ms ± 3.61 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
287 ms ± 9.02 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

It's clear that for large output dataset, the new version is faster.