POC + WIP: Track current PyGMT figure to avoid calling the figure module repeatly

[seisman]

Description of proposed changes

In all Figure methods, the Session._preprocess method (or the Session._activate_figure method) is called before we call the actual plotting method. The Session._activate_figure method activates the figure of the current Figure object so that any subsequent plotting commands write to this figure. Calling the method is necessary when we have multiple Figure instances created and use them in a unfixed order. For example, it's necessary in the following case:

fig1 = pygmt.Figure()
fig2 = pygmt.Figure()
fig1.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
fig2.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
fig1.show()
fig2.show()

However, in cases where we only have one Figure instance or new Figure instance is created after we have finished the previous figure, calling Session._activate_figure is not needed. For example:

fig1 = pygmt.Figure()
fig1.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
fig1.show()

fig2 = pygmt.Figure()
fig2.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
fig2.show()

Thus, it would be good if we can only calling Session._activate_figure when necessary. This can be done by having a global PyGMT state variable that tracks the current activated figure. This PR serves as a proof of concept and it shows some performance improvements.

The PyGMT state variable was initially proposed in #2388.

[codspeed-hq]

CodSpeed Performance Report

Merging #3397 will improve performances by 55.13%

_{Comparing states/figure (9f4839c) with main (f9cf17c)}

Summary

⚡ 25 improvements
✅ 76 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	states/figure	Change
⚡	test_basemap	14.2 ms	10.5 ms	+35.36%
⚡	test_colorbar	14.6 ms	10.9 ms	+34.06%
⚡	test_config_format_date_map	36.9 ms	33 ms	+11.86%
⚡	test_figure_repr	32.2 ms	21 ms	+52.93%
⚡	test_grd2cpt	37.7 ms	30.4 ms	+24.23%
⚡	test_grdcontour_labels	17.7 ms	14 ms	+26.41%
⚡	test_histogram[Series]	14.6 ms	11 ms	+33.17%
⚡	test_histogram[list]	14.6 ms	10.9 ms	+33.76%
⚡	test_legend_entries	123.7 ms	104.8 ms	+18.03%
⚡	test_meca_spec_multiple_focalmecha[array2d]	26.6 ms	19 ms	+40%
⚡	test_meca_spec_multiple_focalmecha[dataframe]	27.2 ms	19.7 ms	+38.55%
⚡	test_meca_spec_multiple_focalmecha[dict_mecha]	27.6 ms	20.1 ms	+37.33%
⚡	test_meca_spec_multiple_focalmecha[dict_mecha_mixed]	27.8 ms	20.2 ms	+37.47%
⚡	test_plot_vectors	15.2 ms	11.4 ms	+33.19%
⚡	test_plot3d_vectors	15.7 ms	11.9 ms	+32.22%
⚡	test_psconvert	23.2 ms	15.6 ms	+49.01%
⚡	test_rose_plot_data_using_cpt	17 ms	13.2 ms	+28.96%
⚡	test_solar_set_terminator_datetime[terminator_datetime1]	23.6 ms	20 ms	+18.21%
⚡	test_solar_set_terminator_datetime[terminator_datetime_string]	24.5 ms	20.8 ms	+17.63%
⚡	test_subplot_basic_frame	54.2 ms	34.9 ms	+55.13%
...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.