refactor: use a custom logger for progress tracking

[tsutterley]

refactor: change formatting of sync program logs
feat: add logger to geocenter, harmonics and spatial classes
fix: updates for typing error with numpy deprecations

[Copilot]

Pull request overview

This PR refactors logging across command-line scripts, mapping utilities, and core gravity_toolkit modules to use a centralized logger helper and standardized run log files, while also addressing numpy indexing/typing updates (e.g., np.nonzero tuple handling) and improving some docstring math notation.

Changes:

• Replace logging.basicConfig(...)/direct logging.* calls with gravtk.utilities.build_logger(...) and per-module loggers; add standardized run-completion logs via gravtk.utilities.create_log_file(...).
• Update multiple numpy indexing patterns (notably np.nonzero(...) unpacking) to np.flatnonzero(...) to avoid typing/shape pitfalls with newer numpy.
• Add/standardize logger usage within several core classes (spatial, harmonics, geocenter) and update documentation to include the new utilities and setup steps.

Reviewed changes

Copilot reviewed 67 out of 67 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
utilities/run_grace_date.py	Switch wrapper program logging to build_logger and use module logger for progress messages.
utilities/quick_mascon_regress.py	Replace np.nonzero unpacking with np.flatnonzero for breakpoint indexing.
utilities/quick_mascon_plot.py	Update month indexing to np.flatnonzero and adjust scalar extraction logic.
utilities/make_grace_index.py	Use module logger for progress output; configure logging via build_logger in main.
scripts/scale_grace_maps.py	Replace custom per-run log writers with create_log_file; convert info/debug output to module logger.
scripts/run_sea_level_equation.py	Add --log option and switch to build_logger; use module logger for iteration output.
scripts/regress_grace_maps.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/piecewise_grace_maps.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/mascon_reconstruct.py	Standardize script logging via build_logger and module logger usage.
scripts/grace_spatial_maps.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/grace_spatial_error.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/grace_raster_grids.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/grace_mean_harmonics.py	Replace custom log writers with create_log_file; move file output logging to class logger.
scripts/convert_harmonics.py	Add --log option and standardize logging via build_logger/create_log_file.
scripts/combine_harmonics.py	Add --log option and standardize logging via build_logger/create_log_file.
scripts/calc_sensitivity_kernel.py	Replace custom log writers with create_log_file; standardize logger usage.
scripts/calc_mascon.py	Replace custom log writers with create_log_file; standardize logger usage.
mapping/plot_QML_grid_3maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_GrIS_grid_movie.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_GrIS_grid_maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_GrIS_grid_5maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_GrIS_grid_3maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_movie.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_9maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_5maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_4maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_global_grid_3maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_AIS_regional_movie.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_AIS_regional_maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_AIS_grid_movie.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_AIS_grid_maps.py	Standardize mapping script logging (module logger + build_logger).
mapping/plot_AIS_grid_4maps.py	Standardize mapping script logging (module logger + build_logger) and formatting adjustments.
mapping/plot_AIS_grid_3maps.py	Standardize mapping script logging (module logger + build_logger).
gravity_toolkit/spatial.py	Add a class-level logger and route read/write informational logs through it.
gravity_toolkit/sea_level_equation.py	Use module logger for verbose outputs instead of root logging.*.
gravity_toolkit/read_love_numbers.py	Use module logger for debug output about input Love number files.
gravity_toolkit/read_GIA_model.py	Use module logger for debug output about input GIA files.
gravity_toolkit/legendre.py	Typing/indexing robustness changes plus docstring math formatting updates.
gravity_toolkit/legendre_polynomials.py	Use np.flatnonzero for polar handling; docstring math formatting updates.
gravity_toolkit/harmonics.py	Add a class-level logger and route read/write informational logs through it.
gravity_toolkit/grace_months_index.py	Replace np.nonzero unpacking with np.flatnonzero for month indexing.
gravity_toolkit/grace_date.py	Add verbosity option + module logger for debug output; configure logger in main.
gravity_toolkit/geocenter.py	Add class-level logger and log debug info for file selection/loading paths.
gravity_toolkit/associated_legendre.py	Docstring math notation updates (raw strings + :math: formatting).
geocenter/monte_carlo_degree_one.py	Replace custom log writers with create_log_file; standardize logger usage.
geocenter/geocenter_processing_centers.py	Replace np.nonzero unpacking with np.flatnonzero for month indexing.
geocenter/geocenter_ocean_models.py	Replace np.nonzero unpacking with np.flatnonzero for month indexing.
geocenter/geocenter_monte_carlo.py	Replace np.nonzero unpacking with np.flatnonzero for month indexing.
geocenter/geocenter_compare_tellus.py	Replace np.nonzero unpacking with np.flatnonzero for month indexing.
geocenter/calc_degree_one.py	Replace custom log writers with create_log_file; standardize logger usage.
doc/source/getting_started/Install.ipynb	Add git lfs fetch --all to installation instructions.
doc/source/api_reference/utilities.rst	Document new build_logger and create_log_file utilities.
dealiasing/dealiasing_monthly_mean.py	Standardize logging via build_logger/module logger; route read/write logs via class logger.
dealiasing/dealiasing_global_uplift.py	Replace custom log writers with create_log_file; standardize logger usage.
dealiasing/aod1b_oblateness.py	Standardize logging via build_logger and module logger.
dealiasing/aod1b_geocenter.py	Standardize logging via build_logger and module logger.
access/podaac_cumulus.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.
access/itsg_graz_grace_sync.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.
access/gfz_isdc_grace_sync.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.
access/gfz_isdc_dealiasing_sync.py	Refactor sync logging to build_logger and ensure log file permissions are applied to the actual file.
access/gfz_icgem_costg_ftp.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.
access/esa_costg_swarm_sync.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.
access/cnes_grace_sync.py	Refactor sync logging to build_logger + unique cache log file; standardize transfer log formatting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 1 comment.

Suppressed comments (8)

access/gfz_isdc_grace_sync.py:109

• Same handler-retention issue as other sync scripts: build_logger won’t replace an existing handler, so a second call in the same process can try to log to an already-closed file stream from a prior run. Clear the module logger’s handlers before configuring logging for this run.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

access/podaac_cumulus.py:120

• build_logger only adds a handler when the named logger has no handlers. If this sync function is invoked multiple times in the same Python process, the existing handler can keep pointing at a previously-closed logfile stream (or an old formatter/stream), causing logs to be dropped or raising I/O on closed file errors. Clear existing handlers for this module logger before (re)building it so each invocation gets a fresh handler/stream.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

access/itsg_graz_grace_sync.py:83

• build_logger won’t update/replace handlers when the logger already has one, so calling this function multiple times in one interpreter session can log to a stale/closed stream from a prior run. Clear the module logger handlers before building the logger for this invocation.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

access/esa_costg_swarm_sync.py:77

• build_logger only adds a handler if none exist. If this function is called more than once in the same process, the logger can retain a handler whose stream was closed at the end of the previous run, causing logging failures. Clear existing handlers for the module logger before building it.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

access/cnes_grace_sync.py:181

• If cnes_grace_sync is invoked multiple times in the same Python process, the module logger can keep an existing handler that points at a previously-closed logfile stream because build_logger does not replace handlers. Clearing handlers before building the logger avoids logging to a stale/closed stream.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

access/gfz_icgem_costg_ftp.py:108

• build_logger does not replace existing handlers. If this sync routine runs more than once in the same interpreter, the logger may still have a handler whose stream was closed at the end of the prior run, causing logs to be dropped or I/O errors. Clear module logger handlers before building the logger for this run.

    # create log file with list of synchronized files (or print to terminal)
    if LOG:
        # output to log file

utilities/run_grace_date.py:85

• build_logger(__name__, ...) configures only the utilities.run_grace_date logger, but gravtk.grace_date() now logs via its own module logger (gravity_toolkit.grace_date). Because build_logger does not configure the root logger, debug/info output from gravity_toolkit.* won’t be shown when running this wrapper. Configure the root logger (name "") so downstream module loggers propagate to it.
  access/gfz_isdc_dealiasing_sync.py:96
• build_logger does not replace existing handlers. If this sync function is called multiple times in the same Python process, the module logger can retain a handler whose stream was closed at the end of a prior run, causing logs to be dropped or raising I/O on closed file errors. Clear existing handlers for the module logger before building it (in both LOG and non-LOG branches) so each invocation gets a fresh handler/stream.

        logger = gravtk.utilities.build_logger(
            __name__, level=logging.INFO, stream=fid1
        )