Metadata-Version: 2.4
Name: orbcloud
Version: 0.1.0
Summary: 3D orbital probability clouds from simulated exoplanet posteriors
Author: Oscar Flores Gaitán, Sam Hopper
License: MIT License
        
        Copyright (c) 2026 Oscar A. Flores Gaitán
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Dynamic: license-file

# orbcloud

`orbcloud` is a Python package designed to transform simulated exoplanet parameter posteriors (such as MCMC chains) into physical 3D orbital probability density clouds.

By plotting thousands of low-opacity orbital paths, the overlapping threads naturally highlight the high-probability regions of 3D orbital space, creating a beautiful and physically accurate visualization.

> [!TIP]
> In addition to visualization, `orbcloud` can be useful to rule out possible dynamical instability in the system. Visually mapping the orbital probability clouds allows researchers to quickly identify overlapping orbital regions. This helps save significant time and computational resources by avoiding expensive N-body simulations if a visual inspection already reveals that the system is most likely going to be unstable.

---

## Features

- **Vectorized Kepler Solver**: Vectorized Newton-Raphson solver to compute eccentric and true anomalies over custom phase grids.
- **Physical Star Customization**: Built-in star properties database (e.g. Vega, Barnard's Star) that automatically adjusts the size and glowing spectral color of the central star.
- **Top (2D) & Lateral (3D) Views**: Easily render orbits in 2D, 3D, or side-by-side.
- **Transparent Alpha-Clouds**: Line-by-line low opacity (`alpha=0.02`) plots that naturally map the probability clouds.
- **Robust Parameter Validation**: Informative alert messages and correction suggestions to prevent unphysical values (e.g. eccentricity $\ge 1.0$) or solver failures.

---

## Installation

```bash
pip install orbcloud
```

Dependencies: `numpy`, `matplotlib`

---

## Quickstart

Here is how to set up and render a multi-planet system:

```python
import matplotlib.pyplot as plt
from orbcloud import PlanetConfig, SystemEnsemble

# 1. Initialize the system around a customized star (e.g. M-type dwarf)
system = SystemEnsemble(star_name="Custom Star", star_mass=1.6, star_type="M")

# 2. Configure planets with mean parameters and uncertainties
planet_b = PlanetConfig(
    name="Planet b",
    P_mean=90.0, P_std=8.0,
    omega_mean_deg=60.0, omega_std_deg=40.0,
    e_mean=0.15, e_std=0.09
)

planet_c = PlanetConfig(
    name="Planet c",
    P_mean=260.0, P_std=14.0,
    omega_mean_deg=210.0, omega_std_deg=45.0,
    e_mean=0.25, e_std=0.10
)

# 3. Add planets to simulate posterior distributions and pre-compute 3D coordinates
system.add_planet(planet_b, num_samples=1000)
system.add_planet(planet_c, num_samples=1000)

# 4. Plot 2D and 3D clouds side-by-side
system.plot_system(show_reference_plane=True)

# 5. Save the result
plt.savefig("system_plot.png", dpi=150, facecolor="white", bbox_inches="tight")
plt.show()
```

---

## Development & Testing

Run unit tests via `pytest`:
```bash
python3 -m pytest -v
```

---

## License

This project is licensed under the MIT License.
