Clarify and harmonize DeltaSigma amplitude unit conventions

[nikosarcevic]

While adding documentation for the forecast unit conventions, we (me and @0Navin0 ) noticed that the data-vector and covariance paths appear to use different DeltaSigma amplitude conventions.

This issue is intended to determine whether the current behavior is intentional or whether the conventions should be harmonized.

Current implementation

Data-vector path

DeltaSigmaCalculator returns:

delta_sigma_msun_mpc2 = np.asarray(mean_sigma - sigma, dtype=float)
delta_sigma_msun_pc2 = delta_sigma_msun_mpc2 / 1.0e12

return np.asarray(delta_sigma_msun_pc2, dtype=float)

and the corresponding docstring states:

Returns:
    Excess surface density DeltaSigma(R) in
    M_sun / pc^2.

This suggests that the forecast data vector is currently expressed in:

Msun / pc^2

Covariance path

The covariance builder uses:

sigma_crit_prefactor_msun_h_pc2()

whose docstring states:

This is the inverse of the prefactor used to compute comoving
Sigma_crit^{-1} in units of pc^2 / (Msol h).

It is intended for calculations where distances are supplied
in Mpc / h and DeltaSigma-like quantities are expressed in
Msol h / pc^2.

This suggests that the covariance normalization is written assuming:

Msun h / pc^2

for DeltaSigma-like quantities.

Question

Are these two conventions intentionally different?

If not, should the forecast data vector and covariance calculations be updated to use a single consistent DeltaSigma amplitude convention throughout the package?

If the distinction is intentional, we should document the rationale explicitly.

How to inspect the relevant code

A quick way to locate the relevant implementation is:

grep -R "delta_sigma\|Sigma\|sigma_crit\|msun\|pc2\|rho_critical" -n src/dsf

The most relevant files are:

src/dsf/data_vector/delta_sigma_builder.py
src/dsf/utils/converters.py
src/dsf/covariance/cov_builder.py
src/dsf/covariance/ingredients/sigma_crit.py

Suggested outcome

Either:

1. Confirm that the current conventions are correct and document them clearly.

or

2. Harmonize the data-vector and covariance paths so that DeltaSigma amplitudes use a single convention throughout DSF.

[0Navin0]

Here's a small test that might help in the debugging process: The plotting code matched the published Delta_Sigma in hMsun/pc^2 units (vs r[Mpc/h]) with the output of calculator.delta_sigma by only increasing the projected distance dfc["r[kpc/h]"] by dividing by h-value. And I didn't need to scale the y-value at all. This implies that the returned values of delta_sigma are likely to be in hMsun/pc^2; and the input radius r to the delta_sigma is, for some reason, assumed in Mpc. Check if this makes sense and if it can guide the search for a potential bug.