orbcloud 0.1.0__py3-none-any.whl

orbcloud/__init__.py

@@ -0,0 +1,8 @@
+"""
+orbcloud - 3D orbital probability clouds from simulated exoplanet posteriors.
+"""
+
+from .sim import PlanetConfig
+from .ensemble import SystemEnsemble
+
+__all__ = ["PlanetConfig", "SystemEnsemble"]

orbcloud/ensemble.py

@@ -0,0 +1,423 @@
+"""
+ensemble.py - Classes representing multi-planet exoplanetary system ensembles.
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+from .sim import PlanetConfig, generate_posterior_samples, STELLAR_DATABASE
+from .kepler_math import kepler_to_cartesian
+
+def _darken_color(hex_color: str, amount: float = 0.25) -> str:
+    """Darkens a hex color by a specified amount (0.0 to 1.0) for the border.
+    
+    Args:
+        hex_color (str): The # + 6 letter/number hexcode of the color of the orbit (e.g #F54927)
+        amount (float): The amount from 0.0 to 1.0 that the color will be darkened (default set to 0.25)
+
+    Returns:
+        The hexcode (str) of the darkened color in the format of #xxxxxx
+    """
+    hex_color = hex_color.lstrip('#')
+    r, g, b = int(hex_color[0:2], 16), int(hex_color[2:4], 16), int(hex_color[4:6], 16)
+    r = int(r * (1.0 - amount))
+    g = int(g * (1.0 - amount))
+    b = int(b * (1.0 - amount))
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+SPECTRAL_COLORS = {
+    'O': '#9bb0ff',
+    'B': '#aabfff',
+    'A': '#cad7ff',
+    'F': '#f8f7ff',
+    'G': '#FFCC00',
+    'K': '#ffd2a1',
+    'M': '#ff9e9e'
+}
+
+SPECTRAL_SIZES = {
+    'O': 150,
+    'B': 120,
+    'A': 90,
+    'F': 80,
+    'G': 70,
+    'K': 60,
+    'M': 45
+}
+
+
+class SystemEnsemble:
+    def __init__(self, star_id: str = 'sun', star_name: str = None, star_mass: float = None, star_type: str = None):
+        '''
+        Args:
+            star_id (str): The id of the star to access the stellar properties in STELLAR_DATABASE (default set to sun)
+            star_name (str): Name of the star (default set to None)
+            star_mass (float): Mass of the star (default set to None)
+            star_type (str): The stellar spectral type of the star (default set to None)
+        
+        '''
+        if star_id is not None and not isinstance(star_id, str):
+            raise TypeError(
+                f"star_id must be a string. Got {type(star_id).__name__}: {star_id!r}. "
+                f"Suggested: 'sun', 'vega', 'barnard'."
+            )
+        self.star_id = star_id.lower() if star_id else None
+        
+        # Determine base properties
+        if self.star_id in STELLAR_DATABASE:
+            base_props = STELLAR_DATABASE[self.star_id]
+        else:
+            base_props = STELLAR_DATABASE['sun']
+            
+        name = star_name if star_name is not None else (base_props['name'] if self.star_id in STELLAR_DATABASE else "Custom Star")
+        
+        if star_mass is not None:
+            if not isinstance(star_mass, (int, float, np.integer, np.floating)):
+                raise TypeError(
+                    f"star_mass must be a numeric value. Got {type(star_mass).__name__}: {star_mass!r}. "
+                    f"Suggested: 1.0 (solar mass)."
+                )
+            if star_mass <= 0:
+                raise ValueError(
+                    f"star_mass must be positive and greater than 0. Got {star_mass}. "
+                    f"Suggested typical values: 1.0 (for solar mass), 0.14 (M dwarf), or 2.1 (A star)."
+                )
+        mass = star_mass if star_mass is not None else base_props['mass']
+
+        if star_type is not None:
+            if not isinstance(star_type, str):
+                raise TypeError(
+                    f"star_type must be a string representing a spectral class. Got {type(star_type).__name__}: {star_type!r}. "
+                    f"Suggested spectral classes: 'O', 'B', 'A', 'F', 'G', 'K', or 'M'."
+                )
+            stype = star_type.upper()
+            if stype not in SPECTRAL_COLORS:
+                raise ValueError(
+                    f"Invalid star_type {star_type!r}. Must be one of the spectral classes: {list(SPECTRAL_COLORS.keys())}. "
+                    f"Suggested: 'G' (like the Sun), 'M' (like Barnard's Star), or 'A' (like Vega)."
+                )
+        else:
+            stype = base_props['type']
+        
+        # Determine color and size
+        if star_type is not None:
+            color = SPECTRAL_COLORS.get(stype, '#fff4e8')
+            size = SPECTRAL_SIZES.get(stype, 70)
+        else:
+            color = base_props['color']
+            size = base_props['size']
+            
+        self.star_props = {
+            'name': name,
+            'type': stype,
+            'mass': mass,
+            'color': color,
+            'size': size
+        }
+        self.m_star = self.star_props['mass']
+        self.planets = {} 
+        
+    def add_planet(self, config: PlanetConfig, num_samples: int = 1000, num_points: int = 200):
+        """Simulates parameter posterior distributions and pre-computes 3D paths for a planet. This function stores the computed orbital coordinates.
+        
+        Args:
+            config (PlanetConfig object): The dataclass storing the planet's orbital parameters
+            num_samples (int): The number of posterior samples to generate (default set to 1000)
+            num_points (int): The number of points to generate (default set to 200)
+
+        Returns:
+            None
+
+        """
+        # Validate inputs
+        if not isinstance(config, PlanetConfig):
+            raise TypeError(
+                f"config must be an instance of PlanetConfig. Got {type(config).__name__}: {config!r}. "
+                f"Please create a PlanetConfig instance first."
+            )
+        if not isinstance(num_samples, (int, np.integer)):
+            raise TypeError(
+                f"num_samples must be an integer. Got {type(num_samples).__name__}: {num_samples!r}. "
+                f"Suggested: 500 or 1000."
+            )
+        if num_samples <= 0:
+            raise ValueError(
+                f"num_samples must be positive and greater than 0. Got {num_samples}. "
+                f"Suggested: 1000."
+            )
+        if not isinstance(num_points, (int, np.integer)):
+            raise TypeError(
+                f"num_points must be an integer. Got {type(num_points).__name__}: {num_points!r}. "
+                f"Suggested: 100 or 200."
+            )
+        if num_points <= 0:
+            raise ValueError(
+                f"num_points must be positive and greater than 0. Got {num_points}. "
+                f"Suggested: 200."
+            )
+
+        # 1. Generate posterior samples
+        samples = generate_posterior_samples(config, num_samples)
+        
+        # 2. Setup standard Mean Anomaly grid
+        M_grid = np.linspace(0.0, 2 * np.pi, num_points)
+        
+        # 3. Compute (num_samples, num_points, 3) coordinate paths for the cloud
+        coords = kepler_to_cartesian(
+            P=samples['P'],
+            e=samples['e'],
+            omega=samples['omega'],
+            i=samples['i'],
+            Omega=samples['Omega'],
+            M_grid=M_grid,
+            m_star=self.m_star
+        )
+        
+        # 4. Compute representative nominal orbit using parameter averages
+        mean_i = np.mean(samples['i'])
+        mean_Omega = np.mean(samples['Omega'])
+        mean_e = config.e_mean if config.e_mean is not None else np.mean(samples['e'])
+        
+        nominal_coords = kepler_to_cartesian(
+            P=np.array([config.P_mean]),
+            e=np.array([mean_e]),
+            omega=np.array([np.radians(config.omega_mean_deg)]),
+            i=np.array([mean_i]),
+            Omega=np.array([mean_Omega]),
+            M_grid=M_grid,
+            m_star=self.m_star
+        )[0]
+        
+        # Store computed coordinates directly
+        self.planets[config.name] = {
+            'coords': coords,
+            'nominal_coords': nominal_coords
+        }
+        
+    def plot_system(
+        self,
+        ax=None,
+        dimension: str = 'both',
+        planets_to_show: list[str] = None,
+        alpha: float = None,
+        alpha_2d: float = 0.02,
+        alpha_3d: float = 0.01,
+        colors: list[str] = None,
+        elev: float = 20.0,
+        azim: float = -60.0,
+        limit_padding: float = 1.02,
+        show_reference_plane: bool = False
+    ):
+        """
+        Plots the exoplanet system in 2D, 3D, or both side-by-side.
+
+        Args:
+            ax (Axes object): Creates a Matplotlib Axes object for plotting (default set to None)
+            dimension (str): Generates a 2D and/or 3D plot of the orbits (default set to 'both')
+            planets_to_show (list[str]): Identifies which planets in the system should be shown on the plot (default set to None)
+            alpha (float): The opacity of the plotted data (deafult set to None)
+            alpha_2d (float): The opacity of the plotted data for the 2D plot (default set to 0.02)
+            alpha_3d (float): The opacity of the plotted data for the 3D plot (default set to 0.01)
+            colors (list[str]): The colors to be used for the orbits (default set to None)
+            elev (float): The elevation of the 3D plot for display (default set to 20.0)
+            azim (float): The azimuth of the 3D plot for display (default set to -60.0)
+            limit_padding (float): Sets the plot axes limits based on the maximum coordinate values (default set to 1.02)
+            show_reference_plane (bool): Shows the reference (0º) plane of the orbits on the 3D plot (default set to false) 
+
+        Returns:
+            ax (Axes object): The 2D and/or 3D plot of the orbits for the planet(s) in the system. 
+
+        """
+        if not isinstance(dimension, str):
+            raise TypeError(f"dimension must be a string. Got {type(dimension).__name__}: {dimension!r}")
+        dimension = dimension.lower()
+        if dimension not in ['2d', '3d', 'both']:
+            raise ValueError(
+                f"dimension must be '2d', '3d', or 'both'. Got {dimension!r}. "
+                f"Suggested: 'both' for 2D & 3D side-by-side, '2d' for top view, or '3d' for lateral view."
+            )
+
+        if planets_to_show is not None:
+            if not isinstance(planets_to_show, list) or not all(isinstance(p, str) for p in planets_to_show):
+                raise TypeError(
+                    f"planets_to_show must be a list of planet name strings. Got {type(planets_to_show).__name__}: {planets_to_show!r}. "
+                    f"Suggested: ['Planet b'] or ['Planet b', 'Planet c']."
+                )
+            for p in planets_to_show:
+                if p not in self.planets:
+                    raise ValueError(
+                        f"Planet {p!r} is not in the system ensemble. "
+                        f"Available planets: {list(self.planets.keys())}. "
+                        f"Please add the planet first using add_planet() or check the name spelling."
+                    )
+
+        if alpha is not None:
+            if not isinstance(alpha, (int, float, np.integer, np.floating)):
+                raise TypeError(f"alpha must be a number. Got {type(alpha).__name__}: {alpha!r}")
+            if not (0.0 <= alpha <= 1.0):
+                raise ValueError(f"alpha must be in the range [0.0, 1.0]. Got {alpha}")
+        
+        if alpha_2d is not None:
+            if not isinstance(alpha_2d, (int, float, np.integer, np.floating)):
+                raise TypeError(f"alpha_2d must be a number. Got {type(alpha_2d).__name__}: {alpha_2d!r}")
+            if not (0.0 <= alpha_2d <= 1.0):
+                raise ValueError(f"alpha_2d must be in the range [0.0, 1.0]. Got {alpha_2d}")
+
+        if alpha_3d is not None:
+            if not isinstance(alpha_3d, (int, float, np.integer, np.floating)):
+                raise TypeError(f"alpha_3d must be a number. Got {type(alpha_3d).__name__}: {alpha_3d!r}")
+            if not (0.0 <= alpha_3d <= 1.0):
+                raise ValueError(f"alpha_3d must be in the range [0.0, 1.0]. Got {alpha_3d}")
+
+        if limit_padding is not None:
+            if not isinstance(limit_padding, (int, float, np.integer, np.floating)):
+                raise TypeError(f"limit_padding must be a number. Got {type(limit_padding).__name__}: {limit_padding!r}")
+            if limit_padding <= 0:
+                raise ValueError(f"limit_padding must be positive and greater than 0. Got {limit_padding}")
+
+        
+        # 1. Handle side-by-side double plot
+        if dimension == 'both':
+            if ax is not None:
+                if isinstance(ax, (list, tuple)) and len(ax) == 2:
+                    ax1, ax2 = ax
+                else:
+                    raise ValueError("For dimension='both', 'ax' must be a list/tuple of two axes [ax2d, ax3d].")
+            else:
+                fig = plt.figure(figsize=(18, 9), facecolor='white')
+                ax1 = fig.add_subplot(121, facecolor='white')
+                ax2 = fig.add_subplot(122, projection='3d', facecolor='white')
+                
+            ax1.set_title("2D Top View", fontsize=13, pad=12)
+            self.plot_system(ax=ax1, dimension='2d', planets_to_show=planets_to_show, alpha=alpha, alpha_2d=alpha_2d, colors=colors, limit_padding=limit_padding)
+            
+            ax2.set_title("3D Lateral View", fontsize=13, pad=12)
+            self.plot_system(ax=ax2, dimension='3d', planets_to_show=planets_to_show, alpha=alpha, alpha_3d=alpha_3d, colors=colors, elev=elev, azim=azim, limit_padding=limit_padding, show_reference_plane=show_reference_plane)
+            
+            return (ax1, ax2)
+
+        if ax is None:
+            fig = plt.figure(figsize=(10, 10), facecolor='white')
+            if dimension == '3d':
+                ax = fig.add_subplot(111, projection='3d', facecolor='white')
+            else:
+                ax = fig.add_subplot(111, facecolor='white')
+            
+        # Get star-specific visual properties
+        star_color = self.star_props.get('color', '#fff4e8')
+        star_edge = _darken_color(star_color, 0.25)
+
+        if dimension == '3d':
+            # Configure light 3D aesthetic
+            ax.set_proj_type('ortho')
+            ax.grid(True, linestyle=':', alpha=0.6, color='gray')
+            
+            ax.xaxis.pane.fill = True
+            ax.yaxis.pane.fill = True
+            ax.zaxis.pane.fill = True
+            ax.xaxis.pane.set_facecolor('#f7f7f7')
+            ax.yaxis.pane.set_facecolor('#f7f7f7')
+            ax.zaxis.pane.set_facecolor('#f7f7f7')
+            
+            # Set viewing angle (defaults to standard perspective)
+            ax.view_init(elev=elev, azim=azim)
+            
+            # Set axis labels
+            ax.set_xlabel('Projected Distance (AU)', labelpad=10)
+            ax.set_ylabel('Projected Distance (AU)', labelpad=10)
+            ax.set_zlabel('Projected Distance (AU)', labelpad=10)
+
+            # Plot glowing central star in 3D
+            ax.scatter(
+                [0], [0], zs=[0],
+                color=star_color,
+                s=self.star_props['size'] * 3, # Make star size visually prominent
+                marker='o',
+                edgecolors=star_edge,
+                linewidths=2,
+                zorder=10,
+                label=self.star_props['name']
+            )
+        else:
+            # Configure standard 2D aesthetic
+            ax.grid(True, linestyle=':', alpha=0.6, color='gray')
+            ax.set_xlabel('Projected Distance (AU)', labelpad=10)
+            ax.set_ylabel('Projected Distance (AU)', labelpad=10)
+
+            # Plot glowing central star in 2D
+            ax.scatter(
+                [0], [0],
+                color=star_color,
+                s=self.star_props['size'] * 3,
+                marker='o',
+                edgecolors=star_edge,
+                linewidths=2,
+                zorder=10,
+                label=self.star_props['name']
+            )
+        
+        # Determine which planets to render
+        planets_list = list(self.planets.keys()) if planets_to_show is None else planets_to_show
+        
+        default_colors = ['#008B8B', '#C71585', '#7B68EE', '#FF8C00']
+        colors = colors or default_colors
+        
+        # Resolve active alpha based on dimension
+        if alpha is not None:
+            active_alpha = alpha
+        else:
+            if dimension == '2d':
+                active_alpha = alpha_2d
+            elif dimension == '3d':
+                active_alpha = alpha_3d
+            else:
+                active_alpha = 0.02  # Fallback
+        
+        # Render selected planet ensembles
+        for idx, name in enumerate(planets_list):
+            if name in self.planets:
+                planet_color = colors[idx % len(colors)]
+                p_data = self.planets[name]
+                
+                # 1. Plot the transparent cloud threads
+                if dimension == '2d':
+                    for orbit in p_data['coords']:
+                        ax.plot(orbit[:, 0], orbit[:, 1], color=planet_color, alpha=active_alpha, lw=0.8)
+                    # 2. Plot nominal orbit
+                    ax.plot(p_data['nominal_coords'][:, 0], p_data['nominal_coords'][:, 1],
+                            color=planet_color, linestyle='--', linewidth=2.5, label=name)
+                else:
+                    for orbit in p_data['coords']:
+                        ax.plot(orbit[:, 0], orbit[:, 1], orbit[:, 2], color=planet_color, alpha=active_alpha, lw=0.8)
+                    # 2. Plot nominal orbit
+                    ax.plot(p_data['nominal_coords'][:, 0], p_data['nominal_coords'][:, 1], p_data['nominal_coords'][:, 2],
+                            color=planet_color, linestyle='--', linewidth=2.5, label=name)
+                
+        # Equalize limits to maintain perfect circle projections
+        all_coords = []
+        for name in planets_list:
+            if name in self.planets and self.planets[name]['coords'] is not None:
+                all_coords.append(self.planets[name]['coords'])
+                
+        if len(all_coords) > 0:
+            stacked = np.concatenate(all_coords, axis=0)
+            max_val = np.max(np.abs(stacked))
+            limit = max_val * limit_padding
+            
+            # Draw a dim gray plane at Z=0 to show the reference plane of the system
+            if dimension == '3d' and show_reference_plane:
+                x_plane = np.linspace(-limit, limit, 10)
+                y_plane = np.linspace(-limit, limit, 10)
+                X_plane, Y_plane = np.meshgrid(x_plane, y_plane)
+                Z_plane = np.zeros_like(X_plane)
+                ax.plot_surface(X_plane, Y_plane, Z_plane, color='gray', alpha=0.1, shade=False, zorder=0)
+            
+            ax.set_xlim(-limit, limit)
+            ax.set_ylim(-limit, limit)
+            if dimension == '3d':
+                ax.set_zlim(-limit, limit)
+                ax.set_box_aspect([1, 1, 1])
+            else:
+                ax.set_aspect('equal')
+            
+        ax.legend(loc='upper left', frameon=True, facecolor='white', edgecolor='lightgray')
+        return ax

orbcloud/kepler_math.py

@@ -0,0 +1,140 @@
+"""
+kepler_math.py - Vectorized Kepler solvers and coordinate projections using a Mean Anomaly phase grid.
+"""
+import numpy as np
+
+def solve_kepler(M: np.ndarray, e: np.ndarray, tol: float = 1e-6, max_iter: int = 100) -> np.ndarray:
+    """
+    Vectorized Newton-Raphson solver for Kepler's Equation: M = E - e*sin(E).
+    
+    Parameters:
+      M: np.ndarray of shape (N_samples, N_points)
+      e: np.ndarray of shape (N_samples, 1) (broadcastable to M)
+    """
+    e_arr = np.asarray(e)
+    if np.any(e_arr < 0.0) or np.any(e_arr >= 1.0):
+        raise ValueError(
+            f"Eccentricity values must be in range [0, 1) for elliptic orbits. "
+            f"Got range [{np.min(e_arr)}, {np.max(e_arr)}]. "
+            f"Suggested typical values: 0.0 (circular), 0.15, or 0.3."
+        )
+
+    E = M.copy()
+    
+    for _ in range(max_iter):
+        f = E - e_arr * np.sin(E) - M
+        f_prime = 1.0 - e_arr * np.cos(E)
+        delta = f / f_prime
+        E -= delta
+        
+        # Check convergence
+        if np.max(np.abs(delta)) < tol:
+            break
+            
+    return E
+
+def kepler_to_cartesian(
+    P: np.ndarray,
+    e: np.ndarray,
+    omega: np.ndarray,
+    i: np.ndarray,
+    Omega: np.ndarray,
+    M_grid: np.ndarray,
+    m_star: float
+) -> np.ndarray:
+    """
+    Converts Keplerian elements to 3D Cartesian coordinates (x, y, z)
+    
+    All inputs P, e, omega, i, Omega are 1D arrays of length N_samples.
+    M_grid is a 1D array of length N_points.
+    
+    Returns an array of shape (N_samples, N_points, 3).
+    """
+    # 1. Type validation for stellar mass
+    if not isinstance(m_star, (int, float, np.integer, np.floating)):
+        raise TypeError(
+            f"Stellar mass (m_star) must be a numeric value. Got {type(m_star).__name__}: {m_star!r}. "
+            f"Suggested: 1.0 (for solar mass)."
+        )
+    if m_star <= 0:
+        raise ValueError(
+            f"Stellar mass (m_star) must be positive and greater than 0. Got {m_star}. "
+            f"Suggested values: 1.0 (for solar mass), 0.14 (M dwarf), or 2.1 (A star)."
+        )
+
+    # 2. Convert and validate inputs are array-like
+    P = np.asarray(P)
+    e = np.asarray(e)
+    omega = np.asarray(omega)
+    i = np.asarray(i)
+    Omega = np.asarray(Omega)
+    M_grid = np.asarray(M_grid)
+
+    if P.ndim != 1 or e.ndim != 1 or omega.ndim != 1 or i.ndim != 1 or Omega.ndim != 1:
+        raise ValueError(
+            f"Orbital elements (P, e, omega, i, Omega) must be 1D arrays representing samples. "
+            f"Got dimensions: P={P.ndim}, e={e.ndim}, omega={omega.ndim}, i={i.ndim}, Omega={Omega.ndim}."
+        )
+
+    lengths = {
+        'P': len(P),
+        'e': len(e),
+        'omega': len(omega),
+        'i': len(i),
+        'Omega': len(Omega)
+    }
+    if len(set(lengths.values())) > 1:
+        raise ValueError(
+            f"All orbital element arrays (P, e, omega, i, Omega) must have the exact same length (number of samples). "
+            f"Got lengths: {lengths}. "
+            f"Please verify your sample generation setup."
+        )
+
+    if len(P) == 0:
+        raise ValueError("Orbital element arrays cannot be empty.")
+    if len(M_grid) == 0:
+        raise ValueError("M_grid (phase points grid) cannot be empty.")
+
+    num_samples = len(P)
+    
+    # Deriving semi-major axis (a) in AU from Period (days) using Kepler's 3rd Law:
+    P_years = P / 365.25
+    a = (P_years**2 * m_star)**(1/3)
+    
+    # Reshape elements to (N_samples, 1) for broadcasting
+    a = a[:, np.newaxis]
+    e = e[:, np.newaxis]
+    i = i[:, np.newaxis]
+    omega = omega[:, np.newaxis]
+    Omega = Omega[:, np.newaxis]
+    
+    # Tile the Mean Anomaly grid (shape: N_samples, N_points)
+    M = np.tile(M_grid, (num_samples, 1))
+    M = M % (2 * np.pi)
+    
+    # Solve Kepler's Equation to get Eccentric Anomaly E
+    E = solve_kepler(M, e)
+    
+    # Position in the orbital plane
+    x_orb = a * (np.cos(E) - e)
+    y_orb = a * np.sqrt(1.0 - e**2) * np.sin(E)
+    
+    # Standard 3D rotations from orbital plane to sky plane (x, y, z)
+    cos_omega, sin_omega = np.cos(omega), np.sin(omega)
+    cos_Omega, sin_Omega = np.cos(Omega), np.sin(Omega)
+    cos_i, sin_i = np.cos(i), np.sin(i)
+    
+    # Rotation transformation
+    x = x_orb * (cos_omega * cos_Omega - sin_omega * sin_Omega * cos_i) - \
+        y_orb * (sin_omega * cos_Omega + cos_omega * sin_Omega * cos_i)
+        
+    y = x_orb * (cos_omega * sin_Omega + sin_omega * cos_Omega * cos_i) - \
+        y_orb * (sin_omega * sin_Omega - cos_omega * cos_Omega * cos_i)
+        
+    z = - x_orb * (sin_omega * sin_i) - \
+        y_orb * (cos_omega * sin_i)
+        
+    # Stack x, y, z into a single (N_samples, N_points, 3) matrix
+    coords = np.stack([x, y, z], axis=-1)
+    
+    return coords

orbcloud/sim.py

@@ -0,0 +1,136 @@
+"""
+sim.py - Simulated exoplanet posterior parameter generator without redundant RV amplitude/epoch parameters.
+"""
+from dataclasses import dataclass
+import numpy as np
+
+# Real-world reference stars mapping spectral type, physical mass (M_sun), and visual properties
+STELLAR_DATABASE = {
+    'theta1': {'name': 'Theta1 Orionis C', 'type': 'O', 'mass': 33.0,  'color': '#9bb0ff', 'size': 150},
+    'achernar':         {'name': 'Achernar',          'type': 'B', 'mass': 6.7,   'color': '#aabfff', 'size': 120},
+    'vega':             {'name': 'Vega',              'type': 'A', 'mass': 2.1,   'color': '#cad7ff', 'size': 90},
+    'upsilon':{'name': 'Upsilon Andromedae','type': 'F', 'mass': 1.3,   'color': '#f8f7ff', 'size': 80},
+    'sun':              {'name': 'The Sun',           'type': 'G', 'mass': 1.0,   'color': '#FFCC00', 'size': 70},
+    'epsilon':  {'name': 'Epsilon Eridani',   'type': 'K', 'mass': 0.82,  'color': '#ffd2a1', 'size': 60},
+    'barnard':    {'name': "Barnard's Star",    'type': 'M', 'mass': 0.144, 'color': '#ff9e9e', 'size': 45}
+}
+
+@dataclass
+class PlanetConfig:
+    name: str
+    P_mean: float          # Period (days)
+    P_std: float           # Period uncertainty (days)
+    omega_mean_deg: float  # Argument of periastron (degrees)
+    omega_std_deg: float   # Argument of periastron uncertainty (degrees)
+    e_mean: float = None   # Eccentricity (None defaults to Beta prior)
+    e_std: float = None    # Eccentricity uncertainty
+    i_deg: float = 0.0     # Fixed inclination (degrees) - defaults to 0
+    Omega_deg: float = 0.0 # Fixed longitude of ascending node (degrees) - defaults to 0
+
+    def __post_init__(self):
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise TypeError(
+                f"Planet name must be a non-empty string. Got {type(self.name).__name__}: {self.name!r}. "
+                f"Suggested: 'Planet b' or 'Kepler-186f'."
+            )
+            
+        def _check_numeric(val, field_name):
+            if not isinstance(val, (int, float, np.integer, np.floating)):
+                raise TypeError(
+                    f"{field_name} must be a number (float or int). Got {type(val).__name__}: {val!r}. "
+                    f"Please check that you didn't pass a string, list, or dictionary."
+                )
+
+        _check_numeric(self.P_mean, "P_mean")
+        _check_numeric(self.P_std, "P_std")
+        _check_numeric(self.omega_mean_deg, "omega_mean_deg")
+        _check_numeric(self.omega_std_deg, "omega_std_deg")
+        _check_numeric(self.i_deg, "i_deg")
+        _check_numeric(self.Omega_deg, "Omega_deg")
+
+        if self.P_mean <= 0:
+            raise ValueError(
+                f"P_mean (period mean) must be positive and greater than 0. Got {self.P_mean}. "
+                f"Suggested: 90.0 or 365.25."
+            )
+        if self.P_std < 0:
+            raise ValueError(
+                f"P_std (period uncertainty) must be non-negative. Got {self.P_std}. "
+                f"Suggested: 5.0 or 0.0."
+            )
+        if self.omega_std_deg < 0:
+            raise ValueError(
+                f"omega_std_deg (omega uncertainty) must be non-negative. Got {self.omega_std_deg}. "
+                f"Suggested: 10.0 or 0.0."
+            )
+
+        if (self.e_mean is None) != (self.e_std is None):
+            raise ValueError(
+                f"Both e_mean and e_std must be specified (or both left as None to use the default Beta prior). "
+                f"Got e_mean={self.e_mean}, e_std={self.e_std}. "
+                f"Please specify both (e.g., e_mean=0.15, e_std=0.05) or omit both."
+            )
+
+        if self.e_mean is not None:
+            _check_numeric(self.e_mean, "e_mean")
+            if not (0.0 <= self.e_mean < 1.0):
+                raise ValueError(
+                    f"e_mean (eccentricity) must be in the range [0, 1) for elliptic orbits. Got {self.e_mean}. "
+                    f"Suggested typical values: 0.0 (circular), 0.15, or 0.3."
+                )
+
+        if self.e_std is not None:
+            _check_numeric(self.e_std, "e_std")
+            if self.e_std < 0:
+                raise ValueError(
+                    f"e_std (eccentricity uncertainty) must be non-negative. Got {self.e_std}. "
+                    f"Suggested: 0.05 or 0.0."
+                )
+
+
+
+def generate_posterior_samples(config: PlanetConfig, num_samples: int = 1000) -> dict:
+    """
+    Simulates posterior distributions for an exoplanet's geometric parameters.
+
+    Args:
+        config (PlanetConfig object): The dataclass storing the planet's orbital parameters
+        num_samples (int): The number of posterior samples to generate to simulate MCMC data (default set to 1000)
+
+    Returns:
+        dict: a dictionary of the posteriors (arrays of length = num_samples) to simulate MCMC data
+            * 'P' (array): Period (days)
+            * 'e' (array): Eccentricity
+            * 'omega' (array): Argument of periapsis (radians)
+            * 'i' (array): Inclination (radians)
+            * 'Omega' (array): Longitude of the ascending node (radians)
+    """
+    rng = np.random.default_rng()
+    
+    # 1. Period (Normal distribution)
+    P = rng.normal(config.P_mean, config.P_std, size=num_samples)
+    P = np.maximum(P, 1e-3)  # Period must be positive
+    
+    # 2. Argument of periastron (Normal distribution in radians, wrapped to [0, 2pi])
+    omega = np.radians(rng.normal(config.omega_mean_deg, config.omega_std_deg, size=num_samples))
+    omega = omega % (2 * np.pi)
+    
+    # 3. Eccentricity (Beta distribution by default, or Normal if configured)
+    if config.e_mean is None or config.e_std is None:
+        # Standard exoplanet prior: Beta(alpha=0.867, beta=3.03) from Kipping 2013
+        e = rng.beta(0.867, 3.03, size=num_samples)
+    else:
+        e = rng.normal(config.e_mean, config.e_std, size=num_samples)
+        e = np.clip(e, 0.0, 0.99)  # Bounded for closed orbits
+        
+    # 4. Fixed 3D orientation parameters (i, Omega)
+    i = np.full(num_samples, np.radians(config.i_deg))
+    Omega = np.full(num_samples, np.radians(config.Omega_deg))
+    
+    return {
+        'P': P,
+        'e': e,
+        'omega': omega,
+        'i': i,
+        'Omega': Omega
+    }

orbcloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+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.

orbcloud-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+orbcloud/__init__.py,sha256=ucbYm_nV7QVo-JBfMUw0_xUb34WjiI7znG1HWX8TptQ,200
+orbcloud/ensemble.py,sha256=8jnUSGIL0WvhKMB7ozF_HXdb5Jy1q5xI8P4c9Gk9UuM,18687
+orbcloud/kepler_math.py,sha256=cPe0lbyAO7M3FE5xFxV8ujvU96H0VWRzqZgUgef79Os,4763
+orbcloud/sim.py,sha256=9KAgBJiLFLrfAAl3832iKe7nekJC-pYs9jJP-ecVzVE,6236
+orbcloud-0.1.0.dist-info/licenses/LICENSE,sha256=yPJmfHiHFS-FVVzHsRwVVVmHgpAizhI0LFOyHM0Us94,1080
+orbcloud-0.1.0.dist-info/METADATA,sha256=myz-Z-uivnZrZbLtKQyLEeULEjMWInEAjv4OvrL4mQg,4683
+orbcloud-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+orbcloud-0.1.0.dist-info/top_level.txt,sha256=OLwk16hoHVbscO2z94IqEO0YNAVN7ZdJ6EyARpB9thc,9
+orbcloud-0.1.0.dist-info/RECORD,,

orbcloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

orbcloud-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

orbcloud-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+orbcloud