betaFeedback

WorksPhysics and Astronomy

Shear Mapping in Python (SMPy): Modular, Extensible, and Accessible Dark Matter Mapping

Abstract

Understanding the Universe's large-scale distribution of dark matter is a central objective in the era of precision cosmology. A key technique for the study of dark matter is weak gravitational lensing: a phenomenon where light from distant galaxies is sheared as it passes through the gravitational field of a massive object, like a galaxy cluster. This shear, which manifests as a slight (weak) distortion of shapes over thousands of galaxies, allows astrophysicists to infer the distribution of total matter, including both luminous and dark matter. Obtaining a mass distribution from a catalog of galaxy shears involves reconstructing the convergence (κκ), the projected surface mass density divided by the critical surface density for the lens-source system. The Shear Mapping in Python (SMPy) package provides a standardized, well-documented, and open-source solution for creating convergence maps from weak lensing galaxy shear measurements. SMPy implements three mapping methods: the classic Kaiser-Squires inversion, aperture mass mapping, and, to our knowledge, the first publicly available implementation of the full KS+ algorithm, which corrects for missing data, field borders, and reduced shear. SMPy was initially developed to support the Superpressure Balloon-borne Imaging Telescope (SuperBIT) and has since evolved into a general-purpose tool suitable for analyzing the weak lensing data from cosmological surveys.

Statement of need

While mass maps are a key deliverable of many cosmological analyses ([7, 10, 13]), scientists are often left to make these maps from scratch. SMPy addresses an outstanding need for the lensing community: an accessible, well-documented, and extensible tool to construct publication-quality mass maps from galaxy shear data. Built on standard scientific Python packages, it provides an easy entry point for researchers new to mass mapping, while also being robust for more senior scientific use.

There are currently three separate mapping methods implemented into SMPy: the classic Kaiser–Squires inversion ([8]), aperture mass mapping ([9, 11]), and notably, to our knowledge, the first publicly available implementation of the full KS+ algorithm ([16]). KS+ improves reconstruction quality by correcting for systematic effects including missing data, field borders, and reduced shear. SMPy also offers specialized and unique features valuable for mass mapping, such as flexible coordinate system support (both celestial and pixel space) and comprehensive signal-to-noise analysis with multiple noise randomization techniques. Figure 1 shows maps of a simulated SuperBIT galaxy cluster observation made with each of the three methods. SMPy is, to our knowledge, the first convergence mapping software to prioritize both accessibility and advanced features.

E-mode maps of a simulated SuperBIT observation of a galaxy cluster

Figure 1. E-mode maps of a simulated SuperBIT observation of a galaxy cluster ([12]) made with the three methods in SMPy: Kaiser–Squires and KS+ convergence, aperture mass, and the Kaiser–Squires signal-to-noise map.

State of the field

The weak lensing community is served by publicly available mapping tools like lenspack [15] and jax-lensing [17], each with their own strengths. jax-lensing excels at neural-network-based approaches and deep learning methods, but applying it to survey-specific data products requires substantial additional development by the end user. lenspack provides well-documented, stand-alone mass-mapping functions, but does not provide an end-to-end convergence-mapping workflow (e.g., configuration management, coordinate handling, noise/SNR analysis, and plotting). In practice, many mass-mapping analyses still rely on bespoke codes built for a specific survey or science case. These gaps, combined with the need for a flexible, configuration-driven, and modular mapping framework, motivated the development of SMPy as an accessible and extensible alternative.

Software design

SMPy was built with the following design principles in mind:

  1. Accessibility: SMPy is written entirely in Python and deliberately relies only on widely-used scientific Python packages (NumPy, SciPy, pandas, Astropy, Matplotlib, and PyYAML). This choice of standard dependencies ensures that users can easily install the packages without complex dependency chains, and that the codebase is maintainable and familiar to the scientific Python community.

  1. Extensibility: SMPy’s modular architecture enables seamless addition of new mass-mapping techniques, encouraging open-source contribution. The framework’s standardized abstract base class architecture allows for the integration of different mapping methods with minimal effort.

  1. Usability: Creating convergence maps with SMPy requires minimal input—users need to only provide a catalog of galaxies with their associated shear components and coordinates. This straightforward input requirement makes the tool accessible to researchers at all levels. A flexible configuration system is integrated via a single YAML file that defines file paths, convergence map algorithm settings, plotting parameters, and more. With this configuration file, the user can create convergence and SNR maps with one line, either via terminal or within code.

  1. Robustness: SMPy is tested against analytical lensing relations and simulated catalogs with known convergence. From the noiseless shear of the simulated field in Figure 1, whose cluster is an NF W halo with M200c=4.1×1014 h−1M⊙M_{200c}=4.1 \times10^{14}\,h^{-1}M_{\odot} at z=0.45z=0.45 [12], Kaiser–Squires and KS+ recover the true convergence with correlations of 0.971 and 0.9996, respectively. Within holes cut in the same field, KS+ reduces the RMS reconstruction error by 56% relative to Kaiser–Squires (Figure 2). The coordinate system abstraction handles both celestial coordinates (using a tangent-plane projection with each shear rotated into the map frame) and pixel-based coordinates through a unified interface. To quantify the significance of the weak lensing detection, multiple noise realizations can be generated using either spatial shuffling (randomizing galaxy positions while preserving shear values) or orientation shuffling (randomizing shear orientations while preserving positions). These noise realizations are mapped with the same method and settings as the observations to estimate the noise in each pixel. The documentation’s

Errors of the Kaiser–Squires and KS+ maps

Figure 2. Errors of the Kaiser–Squires and KS+ maps made from the noiseless shear of the cluster in Figure 1, with each map’s mean removed. Top: the true convergence and each map’s error, smoothed like the maps. Bottom: the same without smoothing, with the galaxies within 1.2 arcmin of eight random points removed (green outlines). KS+ removes the Kaiser–Squires error along the field border.

validation page describes how the simulated catalog was made, how Figure 2 and the numbers above were produced, and the remaining tests.

These design decisions are reflected in SMPy’s overall workflow: users provide a shear catalog and a single YAML configuration file, and SMPy produces convergence maps, signal-to-noise maps, and publication-quality plots with minimal boilerplate. The mapping framework is implemented through standardized abstract base classes, allowing different reconstruction methods to be interchanged while preserving a consistent interface and coordinate-system handling.

On an Apple M4 Pro, a 1024×10241024 \times1024 map from 10.5 million galaxies takes 0.9 s with Kaiser–Squires, 1.8 s with aperture mass, and 506 s with KS+, using default settings. For a cluster-sized field like that of Figure 1, a 57×3857 \times38 map from 8,767 galaxies, Kaiser–Squires takes 4 ms, aperture mass 8 ms, and KS+ 0.7 s. The higher cost of KS+ reflects its 300 iterations on an extended field. Further timing measurements and scaling details are provided in the documentation’s performance page.

Research impact statement

SMPy was initially developed as part of the weak lensing analysis pipeline for SuperBIT, and it was used to create the first convergence maps measured from the stratosphere, presented in “Lensing in the Blue IV” (Saha, Amit, et al., 2026). These maps were made from the weak lensing shape catalogs of the 30 galaxy clusters observed on SuperBIT’s 2023 science flight, presented in “Lensing in the Blue III” [19]. In addition, SMPy has been presented at the Jet Propulsion Laboratory, and we have received interest in exploring integration into Euclid weak-lensing analysis workflows.

AI usage disclosure

Generative AI was used in this work. First, Claude Sonnet 4 (with Extended Thinking enabled via the Claude.ai web interface) was used to assist in implementing the KS+ algorithm in SMPy. The author reviewed all AI-assisted code line-by-line against the Algorithm 1 description in Appendix A of Pires et al. [16] and validated the implementation by injecting fiducial star masks into data and confirming that the reconstruction behaved as expected. Second, OpenAI’s ChatGPT (5.0-Thinking and 5.2-Thinking) models have been used for generating unit tests for the codebase via the Codex CLI. Lastly, both OpenAI’s ChatGPT models and Anthropic’s Claude models have been used in the GitHub App harness to review pull requests and catch bugs.

During the JOSS peer-review revision, Anthropic’s Claude Opus 5.5, via Claude Desktop, assisted with code review and revision, documentation, and validation/testing scripts. The author made the design decisions, reviewed and approved each change, and checked all results. The authors take full responsibility for this work.

Software references

SMPy is written in Python 3.10+ and uses the following packages:

  • NumPy [5]

  • SciPy [23]

  • pandas [14]

  • Astropy [3, 2, 1]

  • Matplotlib [6]

  • PyYAML [20]

Acknowledgements

This material is based upon work supported by a Northeastern University Undergraduate Research and Fellowships PEAK Summit Award.

References

References

  1. [1]Astropy Collaboration, Price-Whelan, A. M., Lim, P. L., Earl, N., Starkman, N., Bradley, L., Shupe, D. L., Patil, A. A., Corrales, L., Brasseur, C. E., Nöthe, M., Donath, A., Tollerud, E., Morris, B. M., Ginsburg, A., Vaher, E., Weaver, B. A., Tocknell, J., Jamieson, W., ... Astropy Project Contributors. (2022). The Astropy Project: Sustaining and growing a community-oriented open-source project and the latest major release (v5.0) of the core package. The Astrophysical Journal, 935(2), 167. https://doi.org/10.3847/1538-4357/ac7c74
  2. [2]Astropy Collaboration, Price-Whelan, A. M., Sipőcz, B. M., Günther, H. M., Lim, P. L., Crawford, S. M., Conseil, S., Shupe, D. L., Craig, M. W., Dencheva, N., Ginsburg, A., VanderPlas, J. T., Bradley, L. D., Pérez-Suárez, D., de Val-Borro, M., Aldcroft, T. L., Cruz, K. L., Robitaille, T. P., Tollerud, E. J., ... Astropy Contributors. (2018). The Astropy Project: Building an open-science project and status of the v2.0 core package. The Astronomical Journal, 156(3), 123. https://doi.org/10.3847/1538-3881/aabc4f
  3. [3]Astropy Collaboration, Robitaille, T. P., Tollerud, E. J., Greenfield, P., Droettboom, M., Bray, E., Aldcroft, T., Davis, M., Ginsburg, A., Price-Whelan, A. M., Kerzendorf, W. E., Conley, A., Crighton, N., Barbary, K., Muna, D., Ferguson, H., Grollier, F., Parikh, M. M., Nair, P. H., ... Streicher, O. (2013). A community Python package for astronomy. Astronomy & Astrophysics, 558, A33. https://doi.org/10.1051/0004-6361/201322068
  4. [5]Harris, C. R., Millman, K. J., Walt, S. J. van der, Gommers, R., Virtanen, P., Cournapeau, D., Wieser, E., Taylor, J., Berg, S., Smith, N. J., Kern, R., Picus, M., Hoyer, S., Kerkwijk, M. H. van, Brett, M., Haldane, A., Río, J. F. del, Wiebe, M., Peterson, P., ... Oliphant, T. E. (2020). Array programming with NumPy. Nature, 585(7825), 357–362. https://doi.org/10.1038/s41586-020-2649-2
  5. [6]Hunter, J. D. (2007). Matplotlib: A 2D graphics environment. Computing in Science & Engineering, 9(3), 90–95. https://doi.org/10.1109/MCSE.2007.55
  6. [7]Jeffrey, N., Gatti, M., Chang, C., Whiteway, L., Demirbozan, U., Kovacs, A., Pollina, G., Bacon, D., Hamanaus, N., Kacprzak, T., Lahav, O., Lanusse, F., Madsley, B., Nadathur, S., Starck, J. L., Vielzeuf, P., Zeurcher, D., Alarcon, A., Amon, A., ... Collaboration, D. (2021). Dark Energy Survey year 3 results: Curved-sky weak lensing mass map reconstruction. Monthly Notices of the Royal Astronomical Society, 505(3), 4626–4645. https://doi.org/10.1093/mnras/stab1495
  7. [8]Kaiser, N., & Squires, G. (1993). Mapping the dark matter with weak gravitational lensing. The Astrophysical Journal, 404, 441–450. https://doi.org/10.1086/172297
  8. [9]Leonard, A., Pires, S., & Starck, J.-L. (2012). Fast calculation of the weak lensing aperture mass statistic. Monthly Notices of the Royal Astronomical Society, 423(4), 3405–3412. https://doi.org/10.1111/j.1365-2966.2012.21133.x
  9. [10]Madhavacheril, M. S., Qu, F. J., Sherwin, B. D., MacCrann, N., Li, Y., Abril-Cabezas, I., Ade, P. A. R., Aiola, S., Alford, T., Amiri, M., Amodeo, S., An, R., Atkins, Z., Austermann, J. E., Battaglia, N., Battistelli, E. S., Beall, J. A., Bean, R., Beringue, B., . . . Zheng, K. (2024). The Atacama Cosmology Telescope: DR6 gravitational lensing map and cosmological parameters. The Astrophysical Journal, 962(2), 113. https://doi.org/10.3847/1538-4357/accf5f
  10. [11]McCleary, J. E., dell’Antonio, I., & Linden, A. von der. (2020). Dark matter distribution of four low-z clusters of galaxies. The Astrophysical Journal, 893(1), 8. https://doi.org/10.3847/1538-4357/ab7c58
  11. [12]McCleary, J. E., Everett, S. W., Shaaban, M. M., Gill, A. S., Vassilakis, G. N., Huff, E. M., Massey, R. J., Benton, S. J., Brown, A. M., Clark, P., Holder, B., Fraisse, A. A., Jauzac, M., Jones, W. C., Lagattuta, D., Leung, J. S.-Y., Li, L., Luu, T. V. T., Nagy, J. M., . . . Tam, S. I. (2023). Lensing in the Blue. II. Estimating the sensitivity of stratospheric balloons to weak gravitational lensing. The Astronomical Journal, 166(3), 134. https://doi.org/10.3847/1538-3881/ace7ca
  12. [13]Oguri, M., Miyazaki, S., Hikage, C., Mandelbaum, R., Utsumi, Y., Miyatake, H., Takada, M., Armstrong, R., Bosch, J., Komiyama, Y., Leauthaud, A., More, S., Nishizawa, A. J., Okabe, N., & Tanaka, M. (2018). Two- and three-dimensional wide-field weak lensing mass maps from the Hyper Suprime-Cam Subaru Strategic Program S16A data. Publications of the Astronomical Society of Japan, 70(SP1), S26. https://doi.org/10.1093/pasj/psx070
  13. [14]Pandas Development Team. (2024). pandas-dev/pandas: pandas (Version v2.2.2). Zenodo. https://doi.org/10.5281/zenodo.10957263
  14. [15]Peel, A. (2020). lenspack: A collection of weak lensing tools in Python (Version 1.0.0). https://github.com/CosmoStat/lenspack
  15. [16]Pires, S., Vandenbussche, V., Kansal, V., Bender, R., Blot, L., Bonino, D., Boucaud, A., Brinchmann, J., Capobianco, V., Carrettero, J., Castellano, M., Cavuoti, S., Clédassou, R., Congedo, G., Conversi, L., Corcione, L., Dubath, F., Fosalba, P., Frailis, M., . . . Wang, Y. (2020). Euclid: Reconstruction of weak-lensing mass maps for non-Gaussianity studies. Astronomy & Astrophysics, 638, A141. https://doi.org/10.1051/0004-6361/201936865
  16. [17]Remy, B., Lanusse, F., Jeffrey, N., Liu, J., Starck, J.-L., Osato, K., & Schrabbach, T. (2023). Probabilistic mass-mapping with neural score estimation. Astronomy & Astrophysics, 672, A51. https://doi.org/10.1051/0004-6361/202243054
  17. [19]Saha, S., McCleary, J. E., Everett, S. W., Amit, M., Vassilakis, G. N., Paracha, E., Fung, L. W. H., Benton, S. J., Jones, W. C., Leroy, G., Huff, E. M., Massey, R., Luu, T. V. T., Gill, A. S., Shaaban, M. M., Voyer, P., Field, A., Brown, A. M., Cerini, G., . . . SuperBIT Collaboration. (2026). Lensing in the Blue. III. Weak-lensing shape catalogs of 30 merging galaxy clusters. The Astrophysical Journal, 1011(1), 102. https://doi.org/10.3847/1538-4357/aeaa5
  18. [20]Simonov, K. (2025). PyYAML. https://pyyaml.org/
  19. [23]Virtanen, P., Gommers, R., Oliphant, T. E., Haberland, M., Reddy, T., Cournapeau, D., Burovski, E., Peterson, P., Weckesser, W., Bright, J., van der Walt, S. J., Brett, M., Wilson, J., Millman, K. J., Mayorov, N., Nelson, A. R. J., Jones, E., Kern, R., Larson, E., . . . SciPy 1.0 Contributors. (2020). SciPy 1.0: Fundamental algorithms for scientific computing in Python. Nature Methods, 17, 261–272. https://doi.org/10.1038/s41592-019-0686-2

Paper details

vlnc:W_g2jhnuph
Version
v1 · latest
Published
Fresh — added to the Hub within the last 30 days
Added
License
CC BY 4.0
Usage

views · 0

downloads · 0

A view counts once per browser per day, a download each time the PDF is requested.

  • Physics and Astronomy

Claude Sonnet 4, 5.0-Thinking, 5.2-Thinking, Claude Opus 5.5 (bare)

View statement
Looking for related papers…
Contents