orbit-gen 0.1.0__tar.gz

orbit_gen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayden Ripic
+
+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.

orbit_gen-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: orbit-gen
+Version: 0.1.0
+Summary: Tools for generating families and orbits in the CR3BP
+Author: Jayden Ripic
+Author-email: Jayden Ripic <jmr595@cornell.edu>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: astropy>=7.2.0
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: spiceypy>=8.1.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# orbit-gen
+
+Periodic orbit family generation and continuation in the Circular Restricted
+Three-Body Problem (CR3BP).
+
+## Overview
+
+`orbit-gen` generates families of periodic orbits in the CR3BP using
+single-shooting differential correction and pseudo-arclength continuation.
+It currently supports various families in the Earth-Moon and Sun-Earth systems.
+
+## Installation
+
+```bash
+pip install orbit-gen
+```
+Requires Python 3.12+.
+
+## Usage
+
+### From a config file
+
+```yaml
+# orbit_config.yaml
+system: SE                      # "EM" (Earth-Moon) or "SE" (Sun-Earth)
+preset: SE_L2_Northern_Halo
+
+max_iter: 1000                  # Maximum Newton iterations for a single differential correct attempt
+eps: 1.0e-6                     # Differential-correction convergence tolerance on residual norm
+step: 0.01                      # Pseudo-arclength continuation step size in canonical units
+max_solutions: 20               # Maximum number of orbits to generate
+max_period_days: 1000.0         # Maximum full orbit period in days
+
+output_dir: results
+show_plots: true                # Optional; for user use only
+```
+
+```python
+from orbit_gen import Family, RunConfig
+
+cfg = RunConfig.from_yaml("orbit_config.yaml")
+fam = Family(cfg)
+
+fam.save()
+if cfg.show_plots:
+    fam.plot()
+```
+
+> **Note:** constructing `Family(cfg)` runs the continuation, but does not save or plot results on its own — call `.save()` / `.plot()` explicitly, as shown above.
+
+### Programmatically
+
+```python
+from orbit_gen import Family, RunConfig
+from orbit_gen.setup.system_config import SE_SYSTEM
+from orbit_gen.setup.presets import PRESETS
+
+cfg = RunConfig(system=SE_SYSTEM, ic=PRESETS["SE_L2_Northern_Halo"])
+fam = Family(cfg)
+fam.save()
+```
+
+Available preset keys (see `orbit_gen.setup.presets.PRESETS`):
+`EM_L2_Northern_Halo`, `EM_DRO_1`, `EM_DRO_2`, `EM_L1`, `EM_Butterfly`,
+`EM_Unnamed_1`, `SE_L2_Northern_Halo`, `SE_L1_Vertical`, `SE_L2_Lyapunov`,
+`SE_L2_Small_Lyapunov`, `SE_L2_Large_Lyapunov`, `SE_L2_Southern_Halo`,
+`SE_Butterfly`, `SE_Dragonfly`.
+
+## Supported Systems
+
+| Key | System |
+|-----|--------|
+| `EM` | Earth-Moon |
+| `SE` | Sun-Earth |
+
+## Output
+
+`fam.save()` writes a `.npz` file (named after the preset, in `cfg.output_dir`)
+containing initial states, periods, and `mu_star` for all converged orbits:
+
+```python
+import numpy as np
+data = np.load("results/SE_L2_Northern_Halo.npz")
+data["states"]              # (N, 6) containing initial [x, y, z, vx, vy, vz] in canonical units for each orbit
+data["periods"]             # (N,) containing full period in canonical units for each orbit
+data["mu_star"]             # System mass ratio
+```
+
+## Contributing
+
+Clone or download the repository and run
+
+```bash
+uv sync
+```
+
+to install the package in editable mode plus dev dependencies. Run the test suite with:
+
+```bash
+uv run pytest
+```
+
+The repo includes a driver script, `scripts/crtbpModel.py`,
+which reads `orbit_config.yaml` from the project root, runs continuation,
+saves results, and shows plots.
+
+An example configuration file (`orbit_config.example.yaml`), is included in the repository, and `orbit_config.yaml` can be created and used by running:
+
+```bash
+cp orbit_config.example.yaml orbit_config.yaml   # edit as needed
+uv run python scripts/crtbpModel.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

orbit_gen-0.1.0/README.md

@@ -0,0 +1,116 @@
+# orbit-gen
+
+Periodic orbit family generation and continuation in the Circular Restricted
+Three-Body Problem (CR3BP).
+
+## Overview
+
+`orbit-gen` generates families of periodic orbits in the CR3BP using
+single-shooting differential correction and pseudo-arclength continuation.
+It currently supports various families in the Earth-Moon and Sun-Earth systems.
+
+## Installation
+
+```bash
+pip install orbit-gen
+```
+Requires Python 3.12+.
+
+## Usage
+
+### From a config file
+
+```yaml
+# orbit_config.yaml
+system: SE                      # "EM" (Earth-Moon) or "SE" (Sun-Earth)
+preset: SE_L2_Northern_Halo
+
+max_iter: 1000                  # Maximum Newton iterations for a single differential correct attempt
+eps: 1.0e-6                     # Differential-correction convergence tolerance on residual norm
+step: 0.01                      # Pseudo-arclength continuation step size in canonical units
+max_solutions: 20               # Maximum number of orbits to generate
+max_period_days: 1000.0         # Maximum full orbit period in days
+
+output_dir: results
+show_plots: true                # Optional; for user use only
+```
+
+```python
+from orbit_gen import Family, RunConfig
+
+cfg = RunConfig.from_yaml("orbit_config.yaml")
+fam = Family(cfg)
+
+fam.save()
+if cfg.show_plots:
+    fam.plot()
+```
+
+> **Note:** constructing `Family(cfg)` runs the continuation, but does not save or plot results on its own — call `.save()` / `.plot()` explicitly, as shown above.
+
+### Programmatically
+
+```python
+from orbit_gen import Family, RunConfig
+from orbit_gen.setup.system_config import SE_SYSTEM
+from orbit_gen.setup.presets import PRESETS
+
+cfg = RunConfig(system=SE_SYSTEM, ic=PRESETS["SE_L2_Northern_Halo"])
+fam = Family(cfg)
+fam.save()
+```
+
+Available preset keys (see `orbit_gen.setup.presets.PRESETS`):
+`EM_L2_Northern_Halo`, `EM_DRO_1`, `EM_DRO_2`, `EM_L1`, `EM_Butterfly`,
+`EM_Unnamed_1`, `SE_L2_Northern_Halo`, `SE_L1_Vertical`, `SE_L2_Lyapunov`,
+`SE_L2_Small_Lyapunov`, `SE_L2_Large_Lyapunov`, `SE_L2_Southern_Halo`,
+`SE_Butterfly`, `SE_Dragonfly`.
+
+## Supported Systems
+
+| Key | System |
+|-----|--------|
+| `EM` | Earth-Moon |
+| `SE` | Sun-Earth |
+
+## Output
+
+`fam.save()` writes a `.npz` file (named after the preset, in `cfg.output_dir`)
+containing initial states, periods, and `mu_star` for all converged orbits:
+
+```python
+import numpy as np
+data = np.load("results/SE_L2_Northern_Halo.npz")
+data["states"]              # (N, 6) containing initial [x, y, z, vx, vy, vz] in canonical units for each orbit
+data["periods"]             # (N,) containing full period in canonical units for each orbit
+data["mu_star"]             # System mass ratio
+```
+
+## Contributing
+
+Clone or download the repository and run
+
+```bash
+uv sync
+```
+
+to install the package in editable mode plus dev dependencies. Run the test suite with:
+
+```bash
+uv run pytest
+```
+
+The repo includes a driver script, `scripts/crtbpModel.py`,
+which reads `orbit_config.yaml` from the project root, runs continuation,
+saves results, and shows plots.
+
+An example configuration file (`orbit_config.example.yaml`), is included in the repository, and `orbit_config.yaml` can be created and used by running:
+
+```bash
+cp orbit_config.example.yaml orbit_config.yaml   # edit as needed
+uv run python scripts/crtbpModel.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

orbit_gen-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "orbit-gen"
+version = "0.1.0"
+description = "Tools for generating families and orbits in the CR3BP"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "astropy>=7.2.0",
+    "matplotlib>=3.10.9",
+    "numpy>=2.4.6",
+    "platformdirs>=4.10.0",
+    "pyyaml>=6.0.3",
+    "scipy>=1.17.1",
+    "spiceypy>=8.1.0",
+]
+
+[[project.authors]]
+name = "Jayden Ripic"
+email = "jmr595@cornell.edu"
+
+[dependency-groups]
+dev = [
+    "deptry>=0.25.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.pytest.ini_options]
+log_cli = true
+log_cli_level = "WARNING"

orbit_gen-0.1.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "orbit-gen"
+version = "0.1.0"
+description = "Tools for generating families and orbits in the CR3BP"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Jayden Ripic", email = "jmr595@cornell.edu" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "astropy>=7.2.0",
+    "matplotlib>=3.10.9",
+    "numpy>=2.4.6",
+    "platformdirs>=4.10.0",
+    "pyyaml>=6.0.3",
+    "scipy>=1.17.1",
+    "spiceypy>=8.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "deptry>=0.25.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.pytest.ini_options]
+log_cli = true
+log_cli_level = "WARNING"

orbit_gen-0.1.0/src/orbit_gen/__init__.py

@@ -0,0 +1,3 @@
+from orbit_gen.orbit import Orbit
+from orbit_gen.family import Family
+from orbit_gen.setup.config import RunConfig

orbit_gen-0.1.0/src/orbit_gen/family.py

@@ -0,0 +1,296 @@
+import numpy as np
+import spiceypy as spice
+from matplotlib import pyplot as plt
+from scipy.optimize import fsolve
+import astropy.units as u
+
+from orbit_gen.utils import eom, units
+from orbit_gen.orbit import Orbit
+from orbit_gen.setup.config import RunConfig
+from orbit_gen.setup.system_config import CanonicalUnits
+
+
+class Family:
+    """Family of CR3BP periodic orbits
+
+    Generates a family of periodic orbits in the circular restricted
+    three-body problem (CR3BP).
+
+    Args:
+        cfg (RunConfig):
+            Full run configuration.
+
+    Attributes:
+        mu_star (float):
+            CR3BP mass ratio.
+        m1 (float):
+            Normalized primary mass (1 - mu_star).
+        m2 (float):
+            Normalized secondary mass (mu_star).
+        r_secondary (float):
+            Radius of the secondary body in canonical distance units (DU).
+        orbits (list[Orbit]):
+            Collection of valid periodic orbit solutions obtained.
+    """
+
+    def __init__(self, cfg: RunConfig):
+        self.cfg = cfg
+        self.orbits: list[Orbit] = []
+
+        self._setup_constants()
+        self._run_continuation()
+
+    def _setup_constants(self):
+        """Load SPICE kernel and compute CR3BP constants from system config."""
+        for path in self.cfg.kernel_paths.values():
+            spice.furnsh(str(path))
+
+        sys = self.cfg.system
+        gm_primary = spice.bodvrd(sys.primary, "GM", 1)[1][0]
+        gm_secondary = spice.bodvrd(sys.secondary, "GM", 1)[1][0]
+
+        self.mu_star = gm_secondary / (gm_primary + gm_secondary)
+        self.m1 = 1 - self.mu_star
+        self.m2 = self.mu_star
+
+        dist_km = sys.canonical_units.dist_km
+        time_seconds = np.sqrt(dist_km**3 / (gm_primary + gm_secondary))
+        sys.canonical_units = CanonicalUnits(
+            dist_km=dist_km, time_days=time_seconds / 86400
+        )
+
+        radii = spice.bodvrd(sys.secondary, "RADII", 3)[1][0]
+        self.r_secondary = units.pos_to_canonical(radii * u.km, sys.canonical_units)
+
+    def _run_continuation(self):
+        """Outer pseudo-arclength loop. Populates self.orbits."""
+        cont = self.cfg.continuation
+        Tp_lim = units.time_to_canonical(
+            cont.max_period_days * u.d, self.cfg.system.canonical_units
+        )
+        stm_identity = np.reshape(np.eye(6), (1, 36))[0]
+
+        # Free variables: [x0, z0, vy0, T/2]
+        X = self.cfg.ic.as_list
+        z = np.array([0.0, 0.0, 0.0, -1.0])
+
+        while X[-1] * 2 < Tp_lim and len(self.orbits) < cont.max_solutions:
+            X, error = self._correct_orbit(X, stm_identity)
+
+            if X[-1] < 0:
+                print("Negative period.")
+                break
+            if error > cont.eps:
+                print("Corrector did not converge.")
+                break
+
+            period_days = units.time_to_dimensional(
+                2 * X[-1], self.cfg.system.canonical_units
+            ).to_value(u.day)
+            print(f"Period: {period_days:.4f} days")
+
+            states, times, valid = self._propagate_and_validate(X)
+
+            if valid:
+                orbit = Orbit(
+                    x0=X[0],
+                    z0=X[1],
+                    vy0=X[2],
+                    period=times[-1],
+                    mu_star=self.mu_star,
+                    canonical_units=self.cfg.system.canonical_units,
+                )
+                # Store already-computed trajectory so propagate() isn't needed again
+                orbit.states = states
+                orbit.times = times
+                self.orbits.append(orbit)
+
+            X, z, success = self._continuation_step(X, z)
+            if not success:
+                break
+
+            print(f"Orbits found: {len(self.orbits)}\n")
+
+        if not self.orbits:
+            raise RuntimeError("Continuation failed")
+
+    def _correct_orbit(self, X: list, stm_identity: np.ndarray) -> tuple[list, float]:
+        """Single-shooting differential corrector
+
+        Newton-style differential correction using a single-shooting formulation
+        for periodic orbit boundary condition enforcement.
+
+        Args:
+            X (array-like):
+                Free-variable vector of the form [x0, z0, vy0, T/2].
+            stm_identity (ndarray):
+                Flattened 6x6 identity matrix used to initialize/propagate the
+                state transition matrix.
+
+        Returns:
+            X (ndarray):
+                Corrected free-variable vector after convergence.
+            error (float):
+                Final residual norm ||F(X)|| at termination.
+        """
+
+        cont = self.cfg.continuation
+        error = np.inf
+
+        for i in range(cont.max_iter):
+            X_full = np.append(X, stm_identity).tolist()
+
+            Fx, state_half_T, Phi = eom.constraint(X_full, self.mu_star)
+            error = np.linalg.norm(Fx)
+
+            if error < cont.eps:
+                break
+
+            dFx = eom.jacobian(X, self.mu_star, state_half_T, Phi)
+            X = X - 0.3 * dFx.T @ (np.linalg.inv(dFx @ dFx.T) @ Fx)
+
+            print(
+                f"  iter {i+1:2d} | error = {error:.3e} | cond = {np.linalg.cond(dFx @ dFx.T):.2e}"
+            )
+
+        return X, error
+
+    def _propagate_and_validate(self, X: list) -> tuple[np.ndarray, np.ndarray, bool]:
+        """Propagate one full orbital period and check secondary-body intersection
+
+        Numerically integrates the trajectory over a full orbital period from the
+        given initial conditions, then evaluates whether the trajectory intersects
+        or enters the secondary body's exclusion region.
+
+        Args:
+            X (array-like):
+                Free-variable vector [x0, z0, vy0, T/2] defining the initial state
+                and half-period used for symmetric propagation.
+
+        Returns:
+            states (ndarray):
+                Propagated state history with shape (N, 6), where each row is
+                [x, y, z, vx, vy, vz].
+            times (ndarray):
+                Time samples corresponding to each state, shape (N,).
+            valid (bool):
+                False if the trajectory intersects the secondary body or violates
+                the exclusion radius; True otherwise.
+        """
+
+        X_full = X.copy()
+        X_full[-1] = 2 * X_full[-1]
+
+        states, times = eom.propagate(X_full, self.mu_star)
+        positions = states[:, 0:3]
+        r_mag = np.linalg.norm(positions, axis=1)
+
+        periapsis_km = units.pos_to_dimensional(
+            min(r_mag), self.cfg.system.canonical_units
+        ).to_value(u.km)
+        print(f"  Periapsis: {periapsis_km:.2f} km")
+
+        valid = not np.any(r_mag < self.r_secondary)
+        if not valid:
+            print("  Intersects secondary — discarding.")
+
+        return states, times, valid
+
+    def _continuation_step(
+        self, X: list, z: np.ndarray
+    ) -> tuple[list, np.ndarray, bool]:
+        """Advance one pseudo-arclength continuation step along an orbit family
+
+        Performs a predictor-corrector step along the solution manifold using a
+        pseudo-arclength continuation method. Advances the current solution estimate
+        and updates the tangent direction along the family.
+
+        Args:
+            X (ndarray):
+                Current free-variable vector at the current solution point.
+            z (ndarray):
+                Current tangent direction vector along the continuation manifold.
+
+        Returns:
+            X_new (ndarray):
+                Predicted/corrected free-variable vector for the next orbit.
+            z_new (ndarray):
+                Updated tangent direction at the new solution point.
+            success (bool):
+                False if the Jacobian is singular or the correction step fails;
+                True otherwise.
+        """
+
+        sol_predictor = X + z * self.cfg.continuation.step
+
+        fss = fsolve(
+            eom.continuation_constraint,
+            X,
+            args=(z, sol_predictor, self.mu_star),
+            full_output=True,
+            xtol=1e-6,
+        )
+        X_new = fss[0]
+
+        # Reconstruct Jacobian
+        Q = fss[1]["fjac"]
+        Rs = fss[1]["r"]
+        R = np.zeros((4, 4))
+        idx, col = np.triu_indices(4, k=0)
+        R[idx, col] = Rs
+        J = Q.T @ R
+
+        try:
+            z_new = np.linalg.inv(J) @ z
+            z_new = z_new / np.linalg.norm(z_new)
+            return X_new, z_new, True
+        except np.linalg.LinAlgError:
+            print("Singular Jacobian — stopping continuation.")
+            return X_new, z, False
+
+    def plot(self):
+        """Plot all orbits in the family on a single 3D figure
+
+        Generates a 3D visualization of all stored periodic orbits in the family,
+        typically in canonical CR3BP coordinates. Each orbit is plotted in the same
+        figure for qualitative comparison of geometry across the continuation family.
+
+        Args:
+            show (bool):
+                If True, displays the figure via matplotlib.pyplot.show().
+                If False, the figure is created but not rendered interactively.
+        """
+
+        fig = plt.figure()
+        ax = fig.add_subplot(projection="3d")
+
+        for orbit in self.orbits:
+            orbit.plot(ax=ax)
+
+        ax.set_title(f"{self.cfg.ic.name} family — {len(self.orbits)} orbits")
+
+        plt.show()
+
+        return ax
+
+    def save(self):
+        """Save all orbit ICs, periods, and mu_star to cfg.output_path."""
+        self.cfg.output_dir.mkdir(parents=True, exist_ok=True)
+
+        states = np.array([o.states[0, :] for o in self.orbits])
+        periods = np.array([o.period for o in self.orbits])
+
+        np.savez(
+            self.cfg.output_path,
+            states=states,
+            periods=periods,
+            mu_star=self.mu_star,
+        )
+        print(f"Saved {len(self.orbits)} orbits to {self.cfg.output_path}")
+
+    def __repr__(self):
+        return (
+            f"Family(system={self.cfg.system.name}, "
+            f"ic={self.cfg.ic.name}, "
+            f"orbits={len(self.orbits)})"
+        )