gh-360: Integrate Dark Emulator function for 3×2pt analysis

[ryusei172525]

🚀 Pull Request Checklist

✅ Summary

Add Dark Emulator integration to cloelib for HSC-Y3 style 3×2pt analysis (WL + GC + GGL). This integrates Dark Emulator's nonlinear power spectrum, halo statistics, and HOD model into cloelib's Protocol-based architecture.

🔄 Changes

• darkemu_utils.py: Add utility functions for Dark Emulator cosmological parameter (cparam) conversion
  • background_to_darkemu_cparam(): Convert cloelib Background to Dark Emulator cparam format
  • validate_darkemu_cparam(): Validate parameters are within emulator training range
  • Neutrino density consistency check with configurable handling
• darkemu_cosmology.py: Add Perturbations-protocol compliant classes
  • DarkEmuNonLinearPerturbations: Nonlinear P(k,z) computation
  • DarkEmuHaloPerturbations: Halo statistics (ξ_hm, ξ_hh, HMF)
  • DarkEmuHODPerturbations: HOD-based ΔΣ, w_p, ξ_gg computation
• darkemu_hod.py: Add HOD parameter management dataclass
  • DarkEmuHODParameters: Zheng+07 HOD model parameters
  • Support for off-centering and incompleteness extensions
• .gitignore: Fix typo %.hdf5 → *.hdf5

🛠 How to Test

from cloelib.auxiliary.darkemu_utils import background_to_darkemu_cparam
from cloelib.cosmology.darkemu_cosmology import DarkEmuHODPerturbations
from cloelib.observables.darkemu_hod import DarkEmuHODParameters

# Set HOD parameters
hod = DarkEmuHODParameters(logMmin=13.13, sigma_sq=0.22, logM1=14.21, alpha=1.13)

# Compute perturbations
pert = DarkEmuHODPerturbations(background, redshifts, hod_params=hod)
ds = pert.delta_sigma(R, z=0.55)
wp = pert.projected_correlation(R, z=0.55)

📝 Documentation

• This PR updates documentation
• This PR does not require documentation changes
• Issue created for documentation update: Don't forget to link the task!

🏗 Related Issues

Resolves #360

📸 Screenshots (if applicable)

N/A

📌 Additional Notes

• Dark Emulator (dark_emulator package) is required as an optional dependency
• Only wCDM models (wa=0) are supported
• Neutrino mass is fixed internally by Dark Emulator (Σm_ν = 0.06 eV)
• @all-contributors please add @ryusei172525 for code, doc

---

✅ PR Checklist for Developers

• I have titled this PR before merging as "gh-#:", where "#" represents the task it closes
• I have run locally pre-commit using pre-commit run --all-files
• I have tested my changes locally
• No new warnings or errors introduced
• I have updated documentation (if applicable)
• My changes do not introduce breaking changes (i.e: the package still gets installed)
• I have added unit tests (if applicable)
• I have consistently updated the GitHub information for the project, including milestones, task types, and other relevant details.

[gcanasherrera]

@all-contributors please add @ryusei172525 for code, doc

[allcontributors]

@gcanasherrera

I've put up a pull request to add @ryusei172525! 🎉

[gcanasherrera]

Hi @ryusei172525 I'm going through this, great work.

I am a bit lost on how you foresee to retrieve the observables (i.e: two point statistics). Do you want to get that from cloelib native functions or through the Dark Emulator? Could you please open a branch in playground with a notebook so I see what is the usage you have in mind?

[ryusei172525]

Hi @gcanasherrera , I’m sorry it took three weeks to prepare everything and kept you waiting.
Thanks for the feedback.

I get the two-point statistics (w_p, ΔΣ for GC/GGL) from the Dark Emulator via cloelib’s wrapper (DarkEmuHODPerturbations), not from cloelib’s native C_ℓ/Limber code. I opened a PR in the playground with notebooks that show this:

• tutorials/dark_emulator/dark_emulator_observables_usage.ipynb explains the choice and shows the concrete retrieval;
• tutorials/dark_emulator/dark_emulator.ipynb is a detailed introduction to the Dark Emulator in cloelib (cosmology, HOD, and computing observables from the emulator);
• the fitting_* notebooks: the end-to-end usage — “get observables from the emulator via cloelib and fit data” — is visible there.

I also opened a PR in cloelike adding EuclidLikelihood_DarkEmu_RealSpace, because the existing likelihoods are C_ℓ-based (photo pipeline) and don’t accept real-space w_p/ΔΣ or use the Dark Emulator — so a dedicated real-space likelihood was needed.

I’d suggest starting with dark_emulator_observables_usage.ipynb in the playground PR to see the usage I have in mind.
There’s also a short video on how to use the notebooks, available in the README at this link.

[gcanasherrera]

@all-contributors please add @HironaoMiyatake for ideas

[allcontributors]

@gcanasherrera

I've put up a pull request to add @HironaoMiyatake! 🎉

[gcanasherrera]

Also @HironaoMiyatake, next time, shout that you provided feedback so I can always track your contributions!!

[gcanasherrera]

@all-contributors please add @ahallcosmo for mentoring

[allcontributors]

@gcanasherrera

I've put up a pull request to add @ahallcosmo! 🎉