Feature/astrometry for testing (v2.1.0 for my own sanity)

[AmberLee2427]

Minimal Astrometry Implementation Notes (Gulls v2.1.0 Release)

Date: December 27, 2025

Feature - Basic Astrometry Support

This PR adds basic astrometric capabilities to Gulls, enabling the simulation of centroid motion for microlensing events. This feature allows users to model and predict the astrometric signatures of lensed sources, which is critical for follow-up observations and event characterization.

What's New

🎯 Astrometry Implementation

• Centroid calculation for lensed sources in the lens frame
• Noise modeling based on photometric precision and seeing conditions
• VBMicrolensing integration using low-level functions for astrometric offsets
• Gould & Yee (2014) noise approximations for realistic uncertainty estimates
• Configurable systematic floor for astrometric uncertainties
• Support for single and binary source configurations with flux-weighted blending

📊 "New" Output Columns

The following columns are added to lightcurve outputs when astrometry is enabled:

• true_x_centroid - True centroid position (x-axis, Einstein radii)
• true_y_centroid - True centroid position (y-axis, Einstein radii)
• x_centroid - Observed centroid with noise (x-axis, Einstein radii)
• y_centroid - Observed centroid with noise (y-axis, Einstein radii)
• x_centroid_err - Uncertainty on x centroid (Einstein radii)
• y_centroid_err - Uncertainty on y centroid (Einstein radii)

⚙️ New Configuration Parameters

• ASTROMETRY_ON (default: 0)

  • Enable/disable astrometric computation and outputs
  • When disabled, all astrometry columns are written as 0.0

• ASTROMETRIC_SYS_FLOOR (default: 0.1 mas)

  • Per-axis systematic floor for astrometric uncertainty
  • Combined in quadrature with photon-limited uncertainties

📚 Documentation

• Comprehensive astrometry guide (documentation/source/astrometry.rst)
  • Detailed parameter descriptions
  • Coordinate system explanations
  • Noise model implementation details
  • Column naming conventions

Technical Details

Coordinate System

Astrometric outputs are currently provided in the lens frame (VBM coordinate system):

• x-axis (x1): along the binary lens axis
• y-axis (x2): perpendicular to the binary lens axis
• Units: Einstein radii (θ_E)

Future PRs will add sky-frame (North/East), absolute RA/Dec outputs and values in mas.

Noise Model

The astrometric uncertainty follows Gould & Yee (2014):

1. Compute fractional photometric error: σ_phot = A_err / max(A_obs, 1e-12)
2. Convert PSF FWHM to Einstein radii: FWHM_er = (FWHM_arcsec * 1000) / θ_E_mas
3. Photon-limited uncertainty: σ_astro = FWHM_er * σ_phot / sqrt(ln(256))
4. Total uncertainty: σ_total = sqrt(σ_astro² + (sys_floor / θ_E_mas)²)

Random Gaussian noise is added to true centroids based on these uncertainties.

Blending

For events with blended light:

• Source centroids are flux-weighted across all blending components
• Includes contributions from the lens star and ambient field stars

Code Changes

Modified Files

• src/structures.h - Added astrometry parameters to Paramfile structure
• src/readParamfile.cpp - Parse new astrometry configuration parameters
• src/pllxLightcurveGenerator.cpp - Compute centroids for single-source events
• src/pllxLightcurveGeneratorMultiple.cpp - Compute centroids for multi-source events
• src/photometry.cpp - Apply noise model and compute observed values
• documentation/source/astrometry.rst - New comprehensive documentation
• README.md - Added feature description

Bug Fixes

• Fixed potential division by zero when θ_E is very small
• Added validation check with warning for events with θ_E < 1e-10 mas
• Fixed variable naming consistency (Asrc → musrc for magnification)
• Corrected spelling errors in comments
• Fixed buffer overflow issues in string formatting

Usage Example

To enable astrometry in your parameter file:

ASTROMETRY_ON 1
ASTROMETRIC_SYS_FLOOR 0.05

Output files will then include the six new centroid columns alongside existing photometric data.

Limitations and Future Work

Current Limitations

• Lens-frame only: Outputs are in Einstein radii in the lens frame
• No sky-frame transformation: North/East and absolute RA/Dec not yet implemented
• No orbital motion effects: Assumes static lens-source geometry per epoch
• Single lens assumption: Blending assumes lens is a single point source (ignoring dark planets, but also not handling binary stars in the lens system)

Planned for Future Featuress

• Sky-frame (North/East) astrometric outputs
• Absolute RA/Dec centroid positions
• Proper motion and parallax effects in sky frame
• Extended source effects for very large sources
• Higher-order astrometric terms

Breaking Changes

None. This is a feature addition with backward compatibility. Existing parameter files will work unchanged with ASTROMETRY_ON defaulting to 0.

Migration Guide

For Existing Users

1. No action required if you don't need astrometry
2. Add two parameters to enable astrometry:
   • ASTROMETRY_ON 1
   • ASTROMETRIC_SYS_FLOOR 0.1 (or your preferred systematic floor)
3. Update output parsing to handle new columns if you enable astrometry
4. Review documentation at documentation/source/astrometry.rst

For Developers

1. Astrometry values are computed in the lightcurve generator and photometry modules
2. VBM low-level functions are used: BinaryMag2() and MultiMag2()
3. True centroids are stored in Event structure during lightcurve generation
4. Noise addition occurs in the photometry module based on observed magnitudes

Performance Impact

Minimal performance impact when astrometry is disabled (default). When enabled:

• Slight increase in computation time due to centroid calculations (not benchmarked)
• Increased output file size due to six additional columns per epoch

Known Issues

• Very small Einstein radii (θ_E < 1e-10 mas) may cause numerical instability
  • A warning is now issued when this occurs
  • Such events are physically unrealistic and thus are improbable; they will have low simulation weights
• Sky-frame outputs are not yet available (issues with coordinate transforms)

Testing

This PR has undergone basic validation:

• Code review via automated PR checks (smoke tests)
• Syntax and compilation verified
• Security scanning with CodeQL
• Sanity checks through inspection of smoke test outputs

A large test set would be a good next step for further validation an sanity checks.

Scientific References

• Gould, A. & Yee, J. C. (2014) - "MICROLENS MASSES FROM ASTROMETRY AND PARALLAX IN SPACE-BASED SURVEYS: FROM PLANETS TO BLACK HOLES"

  • Provides the noise model implementation used in this release
  • Reference for photon-limited astrometric precision

• Penny et al. (2013, 2014, 2019) - Original Gulls papers

  • Core microlensing simulation methodology

Acknowledgments

This PR adds an important capability for astrometric microlensing studies. The implementation leverages the VBMicrolensing library's low-level functions for efficient centroid calculations and Gulls-compatible parameterization.

Getting Started

1. Update Gulls - Pull or download v2.1.0
2. Review documentation - See documentation/source/astrometry.rst
3. Enable astrometry - Add parameters to your .prm file
4. Run simulations - Output files will include new centroid columns
5. Get help - Open an issue or check the documentation

What's Included

• Source code: Complete Gulls source with astrometry support
• Documentation: Updated user guide with astrometry details
• Example configurations: See documentation for parameter examples

Full Changelog

See CHANGELOG.md for the complete list of changes.

---

Previous version: v2.0.0 (October 2025) - Release automation, CMake, validation, binary sources, and CI smoke tests
Next Planned Release: v2.2.0 (Sky-frame and mutli-lens astrometry support)

Smoke Test Results

This PR was validated with automated smoke tests. The plots below show sample lightcurves generated by the different Gulls executables:

smoke_croin_0_0_0.all_astrometry_plot.png

smoke_croin_0_0_0.all_plot.png

smoke_croin_binary_0_0_0.det_astrometry_plot.png

smoke_croin_binary_0_0_0.det_plot.png

smoke_fish_0_0_0.all_astrometry_plot.png

smoke_fish_0_0_0.all_plot.png

smoke_fish_binary_0_0_0.det_astrometry_plot.png

smoke_fish_binary_0_0_0.det_plot.png

smoke_std_0_0_0.all_astrometry_plot.png

smoke_std_0_0_0.all_plot.png

smoke_std_binary_0_0_0.det_astrometry_plot.png

smoke_std_binary_0_0_0.det_plot.png