# Changelog

## [1.0.0] — 2026-10-05

### Release preparation — 2026-10-05

- Preserve subnormal cross-covariances during Cholesky symmetrization and
  source-correlation conversion when component errors have disparate scales.
- Stabilize bootstrap bias and RMS when their intermediate sums or squares
  would overflow or underflow despite finite results.
- Reject singular source correlations consistently in dense and chunked fits
  across NumPy 1.x and 2.x exception hierarchies.
- Restore missing analysis, package-import and legacy tests, and clarify
  pure-family physical-parameter and bootstrap result descriptions.
- Correct obsolete chunked fitting interfaces and commands in the guide.
- Include test helpers and documentation in source distributions, modernize
  license metadata, and add an optional release-tool dependency group.
- Stop publication after build or metadata-check failure, resolve release
  script paths relative to the checkout, and validate explicitly named tags.

### Module and test audit — 2026-10-04

- Fixed catalogue preparation with compact error columns and corrected tests
  that still expected an automatically materialized covariance matrix.
- Fixed the dense clipping source-error entry point, aligned chunked coordinate
  shape validation, and validated full covariance before an initial selection
  could conceal a non-positive-definite input.
- Improved covariance conversion, weighted summaries, standard deviation,
  robust scatter and bootstrap summaries at disparate numerical scales.
- Fixed NPZ metadata serialization for NumPy extended-precision scalar controls.
- Fixed legacy single-mode polar precision, invalid harmonic extraction,
  minimum bootstrap resampling count and partial-cache cleanup.
- Added independent mathematical and GLS checks, chunked-path tests, tests for
  the unified analysis and package imports, and legacy regression coverage.
- Reviewed test expectations and tolerances, including higher-degree mode
  selection; simplified redundant code and unnecessary short-call wrapping.
- Updated README examples and module documentation for chunked fitting,
  catalogue weights, unified analysis and the current legacy package path.

## [0.2.0.dev1] — 2026-10-04

### Codebase refactoring

#### Catalog data adapters (`catalog.py`) — 2026-10-03

- Added adapters for Astropy `Table` and `QTable` inputs, with explicit
  column mapping, unit handling, and missing-value validation.
- Prioritized column unit metadata when interpreting input data.
- Supported mutually exclusive weighting options through error
  columns, a full covariance matrix, or unit weights.
- Preserved cross-source correlations and the component ordering
  required by the fitting interfaces.
- Required the first VSH component to include the `cos(dec)` factor,
  without applying an automatic conversion.
- Added configurable invalid-data handling: raise an error by default,
  or drop invalid sources and subset the covariance matrix consistently.
- Retained original row indices and source identifiers after filtering.
- Added `.fit()` and `.fit_clipped()` methods for direct integration
  with the fitting and clipping interfaces.

#### Code readability — 2026-10-03

- Replaced conditional expressions with explicit `if`/`else`
  statements in the revised modules.
- Simplified unnecessary line breaks in short function calls
  and declarations.

#### Legacy code organization — 2026-10-03

- Renamed the legacy subpackage from `legacy_harmonics` to `legacy`.
- Consolidated the RGQ implementation in `legacy/rgq_func.py`,
  retaining the existing formulas and parameter ordering.
- Deferred relocation of `matrix_calc.py` while existing modules
  still depend on its current location.

#### Legacy matrix calculations (`matrix_calc.py`) — 2026-10-03

- Improved input-length validation and handling of residuals
  supplied as column vectors.
- Added unique cache prefixes to reduce cache-file collisions.
- Moved temporary-directory initialization into the functions
  that require it, avoiding module-level initialization.
- Preserved existing interfaces, including the misspelled
  `nor_mat_calc_from_cahce` name as a compatibility alias.

#### Legacy RGQ functions (`legacy/rgq_func.py`) — 2026-10-03

- Added array conversion and validation of finite values,
  supported degrees, and coordinate broadcasting.
- Replaced `sys.exit` calls with exceptions.
- Clarified that `l_max=2` includes both degree-one and
  degree-two terms.
- Preserved the original analytical expressions and
  physical-parameter ordering.

#### Simulation example (`examples/generate_test_data.py`) — 2026-10-03

- Moved the simulation script into `examples`, retaining
  the filename and original simulation workflow.
- Added default parameters for the `l_max=1` case.
- Added validation of `sample_size`.
- Preserved the original sampling scheme, zero-noise setup,
  output columns, and two-million-source example.

#### Legacy bootstrap (`legacy/bootstrap_sample.py`) — 2026-10-04

- Fixed array comparisons with `None`, forwarding of `bs_freq`,
  undefined fitting variables, and unpacking of dictionary results.
- Preserved existing interfaces, the resampling-count formula,
  and the original statistical conventions.

#### Legacy statistics (`legacy/vsh_stats.py`) — 2026-10-04

- Removed the redundant `vsh_stat.py` module and retained
  `vsh_stats.py` in the legacy subpackage.
- Added support for list inputs and early validation of array
  shapes, uncertainties, and degrees of freedom.
- Improved display precision for goodness-of-fit statistics.
- Preserved existing interfaces, output fields, and statistical
  conventions.

#### Legacy auxiliary information (`legacy/vsh_aux_info.py`) — 2026-10-04

- Added integer and range validation, rejecting boolean and
  floating-point values for integer arguments.
- Replaced process termination with `ValueError` when the
  sample contains too few observations.
- Preserved support for exactly determined systems and clarified
  that observation-count checks do not guarantee full rank.

#### Legacy harmonic power (`legacy/vsh_power.py`) — 2026-10-04

- Fixed recognition of the default `"Full"` fit type and an
  undefined variable in the pure spheroidal branch.
- Converted numerical inputs to `float64` before squaring
  to avoid integer overflow.
- Added degree, shape, and finite-value validation, replacing
  process termination with exceptions.
- Preserved coefficient ordering and power normalization.
- Retained signed remaining-power values without clipping
  negative results to zero.

#### Legacy significance (`legacy/vsh_significance.py`) — 2026-10-04

- Fixed an undefined variable in normalization method 2,
  incorrect uncertainty arguments for pure T/S models,
  and misplaced `fit_type` and `nor_type` arguments.
- Corrected the degrees of freedom used in Z statistics
  and prevented integer truncation.
- Displayed `--` for unavailable components and statistics
  that cannot be evaluated from negative remaining power.
- Preserved the three legacy normalization formulas and
  documented their neglect of coefficient correlations
  and the approximate nature of Z statistics.

#### Legacy fitting (`legacy/vsh_fit.py`) — 2026-10-04

- Preserved all six public function signatures.
- Corrected parameter counts and degrees of freedom
  for pure toroidal and spheroidal fits.
- Corrected uncertainty scaling after outlier removal.
- Improved exception handling to avoid silently hiding failures.
- Fixed table-column matching and handling of zero residuals.

#### Legacy tuning example (`examples/tune_para.py`) — 2026-10-04

- Moved `tune_para.py` into `examples` as a diagnostic script
  for the legacy batch-fitting implementation.
- Fixed parameter-degree consistency and unpacking of
  dictionary results.
- Prevented the experiment from running automatically on import.
- Set the default experiment to 5,000 sources, degree two,
  and `num_iter` values from 10 to 200.

#### Obsolete test scripts — 2026-10-04

- Removed the outdated `verify_code.py` and
  `implementation_comparison.py` scripts.

#### Direct physical-parameter fitting (`legacy/rgq_fit.py`) — 2026-10-04

- Renamed the former `legacy.py` fitting module to
  `legacy/rgq_fit.py`.
- Retained direct fitting of rotation, glide, and quadrupole
  parameters, preserving existing interfaces and parameter ordering.
- Corrected weight-matrix ordering to match the observation vector.
- Corrected eight degree-two partial derivatives in the
  declination component.
- Fixed goodness-of-fit calculations and handling of degrees
  of freedom.
- Updated outlier iteration to recompute residuals for the full
  sample and allow previously rejected sources to re-enter.
- Corrected sample-mask mapping and statistics after filtering.
- Improved input validation and rank-deficiency handling.

#### Obsolete test script cleanup — 2026-10-04

- Removed the obsolete `test.py` script.

#### Chunked least-squares solving — 2026-10-04

- Added block-wise whitening and QR compression, followed by
  SVD of the reduced system.
- Avoided constructing the full design matrix for large samples.
- Supported independent sources with correlated RA/Dec
  components within each source.
- Retained the dense solver for full cross-source covariance.

#### Unified fitting interfaces (`fitting.py`) — 2026-10-04

- Unified dense and chunked fitting through the `method` argument
  of `fit_vsh` and `fit_ssh`.
- Replaced separate public chunked-fitting wrappers with
  `method="chunked"`.
- Added direct support for component uncertainties and
  within-source correlations through `sigma_ra`, `sigma_dec`,
  and `rho` in VSH fitting.
- Restricted full observation covariance matrices to
  `method="dense"`.

#### Compact catalog uncertainties (`catalog.py`) — 2026-10-04

- Stored per-source uncertainties and correlations separately,
  avoiding premature construction of dense covariance matrices
  for chunked fitting.
- Preserved uncertainty information when selecting source subsets.
- Corrected dataclass field ordering so that required fields
  precede fields with default values.
- Aligned catalog construction with the revised field layout.

#### Chunked outlier clipping (`clipping.py`) — 2026-10-04

- Extended `fit_vsh_clipped` and `fit_ssh_clipped` to support
  chunked fitting.
- Evaluated residuals and clipping scores in blocks over all
  original sources after each fit.
- Allowed previously rejected sources to re-enter the fit.
- Required identical consecutive selection masks for convergence.
- Returned the last actually fitted mask when the iteration
  limit was reached, keeping the mask consistent with the fit.
- Added `store_residuals` and `store_scores` options to control
  retained output arrays.
- Retained global score storage when required for median-based
  clipping thresholds.

## [0.2.0.dev0] — 2026-10-03

### Codebase refactoring

#### Spherical-harmonic bases (`basis.py`) — 2026-10-02

- Consolidated VSH and SSH basis construction into a single module.
- Added public interfaces for basis evaluation and coefficient naming:
  `vsh_basis`, `vsh_coefficient_names`, `ssh_basis`, and
  `ssh_coefficient_names`.

#### Covariance handling (`covariance.py`) — 2026-10-03

- Centralized covariance matrix construction, conversion, and validation.
- Vectorized covariance matrix construction for paired astrometric
  components, including correlations between the two components.
- Added Cholesky-based whitening of observations and design matrices
  for weighted least-squares fitting.
- Supported reuse of Cholesky factors to avoid repeated factorization.

#### Least-squares solver (`solver.py`) — 2026-10-03

- Added SVD-based least-squares solving of whitened observations
  and design matrices.
- Supported full covariance matrices, reusable `CovarianceFactor`
  objects, and unit covariance.
- Returned fitted coefficients, coefficient covariance, residuals
  in the original observation space, chi-square, degrees of freedom,
  rank, and singular values.
- Added configurable rank detection through `rcond` and explicit
  errors for rank-deficient systems.
- Preserved coefficient covariance without automatic scaling by
  reduced chi-square.

#### Model evaluation (`model.py`) — 2026-10-03

- Added `predict_vsh` and `predict_ssh` for evaluating spherical-harmonic
  models from coefficient vectors.
- Added `residual_vsh` and `residual_ssh`, with residuals defined as
  observations minus model predictions.
- Standardized VSH outputs as `(2, N)`, with the right-ascension tangent
  component first and the declination component second, and SSH outputs
  as `(N,)`, consistent with `basis.py`.
- Added block-wise model evaluation with a default `block_size=10000`;
  setting `block_size=None` evaluates all sources at once.
- Kept model evaluation independent of observation covariance.

#### Fitting interfaces (`fitting.py`) — 2026-10-03

- Added `fit_vsh` and `fit_ssh` as public interfaces for fitting
  spherical-harmonic models to a fixed sample.
- Integrated basis construction, covariance handling, and
  least-squares solving into a unified fitting workflow.
- Supported full observation covariance matrices, including
  correlations between sources.
- Standardized VSH observation ordering as all right-ascension
  tangent components followed by all declination components,
  with residuals returned as `(2, N)`.
- Returned fitted coefficients, coefficient names, coefficient
  covariance, residuals, chi-square, and degrees of freedom.
- Preserved coefficient covariance without automatic scaling
  by reduced chi-square.

#### Statistical diagnostics (`statistics.py`) — 2026-10-03

- Centralized RMS, weighted RMS, standard deviation, and weighted
  scatter calculations.
- Distinguished zero-referenced RMS/WRMS from mean-subtracted
  scatter statistics.
- Added chi-square calculations using full observation covariance.
- Added coefficient uncertainty and correlation matrix calculations
  from coefficient covariance.
- Corrected legacy issues involving overwritten bias values,
  uninitialized variables in the unweighted branch, and use of
  right-ascension bias for declination statistics.
- Clarified covariance, correlation, and degrees-of-freedom handling.

#### Iterative outlier clipping (`clipping.py`) — 2026-10-03

- Added `fit_vsh_clipped` and `fit_ssh_clipped` for iterative fitting
  with outlier rejection.
- Supported absolute and median-based clipping thresholds,
  with two-dimensional normalized residual distances for VSH.
- Refitted the model using the currently retained sources and
  recomputed observation-minus-model residuals for all original
  sources at each iteration.
- Rebuilt the selection mask from the full sample, allowing
  previously rejected sources to re-enter the fit.
- Defined convergence as an unchanged selection mask between
  consecutive iterations.
- Computed median-based thresholds using the full sample.
- Preserved the appropriate rows and columns of the full covariance
  matrix when selecting observations for each fit.
- Returned the final fit, selection mask, full-sample residuals
  and clipping scores, convergence status, and iteration history.

#### Physical parameter conversion (`parameters.py`) — 2026-10-03

- Added conversion of VSH coefficients to rotation, glide, and
  quadrupole parameters.
- Supported combined toroidal/spheroidal models and pure toroidal
  or spheroidal models.
- Corrected degree-two coefficient indexing for pure T/S models.
- Propagated the full coefficient covariance to physical parameters,
  preserving parameter correlations.
- Added `physical_from_fit` for extracting physical parameters
  and their uncertainties from fitting results.
- Added `vector_apex` for computing vector amplitude and apex
  coordinates, with covariance propagation retaining correlations
  between amplitude, right ascension, and declination.
- Handled undefined directions and singular directional uncertainties
  using `NaN` for zero vectors and polar cases, as appropriate.

#### Harmonic power and significance (`power.py`) — 2026-10-03

- Added degree-wise toroidal, spheroidal, and total VSH power,
  together with SSH power including degree zero.
- Applied a factor of two to contributions from coefficients
  with positive order (`m > 0`), consistent with the coefficient
  convention used in `basis.py`.
- Added significance testing based on the full-covariance Wald
  statistic by default, including correlations between toroidal
  and spheroidal coefficients in joint tests.
- Supported `zonal`, `diagonal`, and `mean` normalization methods.
- Added `power_from_fit` and `significance_from_fit` for direct
  analysis of fitting results.
- Corrected legacy significance calculations involving undefined
  variables, coefficient/error arguments, and degrees of freedom.

#### Bootstrap uncertainty estimation (`bootstrap.py`) — 2026-10-03

- Added bootstrap uncertainty estimation for VSH and SSH fits,
  including derived physical parameters.
- Supported source-level pairs resampling as the default method,
  keeping each source's components together and requiring
  independence between sources.
- Added parametric resampling with Gaussian noise at fixed source
  positions, supporting full cross-source covariance.
- Optimized parametric resampling for fixed-sample linear models
  by generating equivalent coefficient samples without repeated
  factorization of large matrices.
- Supported configurable resampling counts and reproducible
  random number generation.
- Returned bootstrap covariance, standard errors, bias estimates,
  and percentile intervals.
- Kept sample selection fixed during resampling; clipping is not
  repeated within individual bootstrap realizations.
