---
title: 'OpenSora-v1.2: Stellar Occultation Analysis'
url: https://www.emergentmind.com/topics/opensora-v1-2
type: topic
---

# OpenSora-v1.2: Stellar Occultation Analysis

OpenSora-v1.2 is the versioned release of SORA (Stellar Occultation Reduction and Analysis), an open-source Python library designed for efficient reduction and analysis of stellar occultation data. Stellar occultations—when a Solar System body transits a background star—provide highly precise astrometric, morphological, and physical diagnostics, often rivaling spacecraft measurements. SORA v1.2 encapsulates algorithms and data pipelines spanning prediction, light-curve modeling, geometric reconstruction, astrometric correction, and visualization. The framework leverages Gaia astrometric catalogs, JPL Horizons/Spice ephemerides, and modern probabilistic modeling to automate the conversion of photometric time series into physical constraints on Solar System bodies [2201.01799].

## 1. Architecture, Prerequisites, and Installation

SORA v1.2 is modular, dependency-aware, and targets environments with Python ≥3.8 and standard astronomy libraries. Installation supports both pip and conda via the `sora-astro` package, providing seamless integration with astropy, astroquery, numpy, scipy, matplotlib, cartopy, and spiceypy. Core architectural modules include:

- `sora.body`, `sora.star`, and `sora.observer`: Definitions for target objects, stars, and observation geometries.
- `sora.prediction`: Event prediction and ephemeris interpolation.
- `sora.lightcurve`: Advanced photometric data modeling.
- `sora.occultation`: Chord fitting, tangent-plane projection, astrometric solution, and physical modeling.

Initialization is verified via:
```python
import sora
print("SORA version:", sora.__version__)  # should show '1.2'
```
This architecture underpins a pipeline in which each functional module can be integrated into custom or scripted analysis routines [2201.01799].

## 2. Prediction Algorithms and Event Characterization

The prediction module, `sora.prediction`, automates retrieval of background star fields from Gaia-DR2/EDR3 using astroquery for a user-specified time window. It interpolates Solar System body ephemerides via SPICE kernels or directly via JPL Horizons outputs. Occultation geometry is computed using a two-point linear interpolation scheme:

\[
CA = \sqrt{\Delta_1^2 - \left(\frac{\Delta_1^2 - \Delta_2^2 + \Delta_B^2}{2\,\Delta_B}\right)^2}
\]
\[
t_0 = t_1 + (t_2 - t_1)\sqrt{\frac{\Delta_1^2 - CA^2}{\Delta_B^2}}
\]
\[
V_S = \frac{D_\circ\,\sin\Delta_B}{t_2 - t_1}
\]

Here, $\Delta_1, \Delta_2$ are star–body separations at epochs $t_1, t_2$, and $\Delta_B$ is the ephemeris separation. Outputs are organized as a `PredictionTable` (a subclass of Astropy Table). Visualization is supported via Earth-shadow maps, providing event context for multi-site observation planning.

Enhancements in v1.2 include direct support for NIMA-style ephemerides, automated RUWE-based screening of Gaia stars, and up-to-date proper motion corrections [2201.01799].

## 3. Photometric Data Reduction and Light-Curve Modeling

The `sora.lightcurve` module implements a workflow-driven reduction chain for time-series photometry. It normalizes baseline flux outside the occultation window via polynomial fitting, and models the occultation using a Fresnel diffraction framework—a straight-bar occultor model adapted from Roques et al. (1987):

- Fresnel scale: $f = \sqrt{\lambda D_\circ / 2}$
- Stellar diameter: Convolution across disk
- Exposure/Dead time integration: Robustly handled

Ingress ($t_i$) and emersion ($t_e$) are fit using parallelized (multi-core) Monte Carlo sampling and $\chi^2$ minimization:
\[
\chi^2 = \sum_{j=1}^N \frac{(\phi_{j,\rm obs} - \phi_{j,\rm model})^2}{\sigma_j^2}
\]
Uncertainties are estimated as:
\[
\sigma_t \approx \frac{\sigma_{\rm LC}}{\Delta f} t_{\rm exp}
\]
where $\sigma_{\rm LC}$ is the baseline noise, and $\Delta f$ is the occultation depth. The module returns robust posterior intervals for timing solutions as a `ChiSquare` object [2201.01799].

## 4. Chord Fitting, Shape Modeling, and Astrometric Solution

Ingress/emersion times are mapped to tangent-plane coordinates using either full parallax+light-time transformation or orthographic approximation:
- Exact tangent-plane: Eq. 12
- Orthographic: Eq. 13–15

Chord length is determined by:
\[
L = V_S (t_e - t_i)
\]
Multiple chords are fit to an ellipse (or circle if $\epsilon'=0$) via a Monte Carlo approach minimizing:
\[
\chi^2 = \sum_{k=1}^M \frac{[(r_{k,\rm obs} - r_{k,\rm model})]^2}{\sigma_k^2 + \sigma_{\rm model}^2}
\]
where $r_{k,\rm obs}$ are chord endpoints and $\sigma_{\rm model}$ is an optional topography-imposed floor.

The fitted ellipse center $(x_c, y_c)$ is referenced to the body’s predicted ICRS ephemeris to yield an absolute astrometric solution:
\[
(\alpha_{\rm body},\,\delta_{\rm body}) = (\alpha_{\rm eph},\,\delta_{\rm eph}) \oplus (x_c/D_\circ,\,y_c/D_\circ)
\]
Error propagation incorporates statistical, catalog, and fit-driven contributions.

## 5. Performance, Usability, and Visualization Enhancements

Version 1.2 introduces substantial performance improvements and usability features:

- Multi-core acceleration of Monte Carlo fits (ellipse: $10^7$ samples in $\approx 18$ s; light-curve: $10^5$ samples in $\approx 3$ s on a 6-core Intel i7).
- Interactive GUI widgets for Jupyter-based chord selection and inspection.
- Customizable cartopy-based map color schemes and live $\chi^2$ parameter exploration surfaces.
- Parallelizable routines via `numba` and `multiprocessing` backends.

The system is architected for reproducible science and extensibility, supporting both command-line and interactive research workflows [2201.01799].

## 6. End-to-End Example: Workflow and Output

A canonical end-to-end workflow with SORA v1.2 encompasses prediction, observer configuration, light curve ingestion, ingress/egress fitting, geometric and astrometric modeling, and visualization. The following excerpt of a script illustrates typical usage:

```python
# Prediction, setup
quaoar = Body(name="(50000) Quaoar", source="SBDB")
preds = predict_occultations(body=quaoar, ...)
star = Star(gaia_id=star_id, catalog="EDR3")
obs_site = Observer(name="La_Silla", code="809")
occ = Occultation(body=quaoar, star=star, ...)
# ...light curve loading, fitting, shape and astrometry computations
```

Typical outputs include:
- Prediction tables (star ID, t_ca, CA, $V_s$, PA, G-mag)
- Light-curve plot with maximum-likelihood or MCMC fit overlay
- Chord diagrams (tangent-plane) with best-fit ellipsoid or circle
- Annotated global shadow map

## 7. Future Developments and References

Planned extensions outlined in §5 of [2201.01799] include further automation, enhanced dynamical modeling, and deeper integration with upcoming astrometric datasets (e.g., post-Gaia releases). The library’s organization and API are designed for integration with legacy and new observatory pipelines as LSST and similar surveys increase the volume and complexity of stellar occultation observations.

Refer to SORA’s primary description [2201.01799] for architectural details, background on the occultation technique (§2), algorithmic specifics (§4), and module-level implementation notes.

Source: https://www.emergentmind.com/topics/opensora-v1-2