ssapy-toolkit 1.0.0__tar.gz

ssapy_toolkit-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Lawrence Livermore National Laboratory
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ssapy_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: ssapy-toolkit
+Version: 1.0.0
+Summary: SSAPy Toolkit: extensions for orbital mechanics, plotting, and data IO
+Author-email: "Travis R. Yeager" <yeagerastro@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Lawrence Livermore National Laboratory
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://github.com/llnl/SSAPy-Toolkit
+Project-URL: Repository, https://github.com/llnl/SSAPy-Toolkit
+Project-URL: Issues, https://github.com/llnl/SSAPy-Toolkit/issues
+Project-URL: Documentation, https://ssapy-toolkit.readthedocs.io/
+Keywords: orbital-mechanics,astrodynamics,visualization,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy
+Requires-Dist: astroquery
+Requires-Dist: corner
+Requires-Dist: emcee
+Requires-Dist: gitpython
+Requires-Dist: h5py
+Requires-Dist: imageio
+Requires-Dist: imageio-ffmpeg
+Requires-Dist: ipykernel
+Requires-Dist: ipympl
+Requires-Dist: ipython
+Requires-Dist: ipytree
+Requires-Dist: ipyvolume
+Requires-Dist: jplephem
+Requires-Dist: llnl-ssapy
+Requires-Dist: lmfit
+Requires-Dist: matplotlib
+Requires-Dist: mpmath
+Requires-Dist: nexusformat
+Requires-Dist: npy-append-array
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: pandas
+Requires-Dist: pillow
+Requires-Dist: psutil
+Requires-Dist: pyerfa
+Requires-Dist: PyPDF2
+Requires-Dist: rebound
+Requires-Dist: regex
+Requires-Dist: requests
+Requires-Dist: scikit-learn
+Requires-Dist: seaborn
+Requires-Dist: selenium
+Requires-Dist: sympy
+Requires-Dist: tqdm
+Requires-Dist: spacetrack
+Requires-Dist: vg
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mpi; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: myst-parser<4.0.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# SSAPy Toolkit
+
+**SSAPy Toolkit** (Python package: `ssapy_toolkit`) is a collection of extensions for the SSAPy ecosystem, providing tools for orbital mechanics, plotting, and data IO to support research and engineering workflows.
+
+SSAPy itself is a fast, flexible, high-fidelity orbital modeling and analysis tool for orbits spanning from low-Earth orbit into the cislunar regime. It supports rich satellite definitions, multiple element types and coordinate frames, configurable force models (Earth and lunar gravity, radiation pressure, drag, planetary perturbations, maneuvers), a variety of integrators, Monte Carlo and UQ workflows, and extensive ground/space observer and plotting capabilities. See the SSAPy repository for full details:
+
+https://github.com/llnl/SSAPy/tree/main
+
+---
+
+## Features
+- Utility functions for orbital mechanics and astrodynamics
+- Coordinate transforms and time conversions
+- Data IO helpers for HDF5, CSV, JSON, and more
+- Plotting helpers for orbits, ground tracks, and dashboards
+
+---
+
+## Installation
+
+SSAPy Toolkit is a standard Python package.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install -e .[dev]
+```
+
+This installs the package in editable mode along with development dependencies (testing, linting, docs tools, etc.).
+
+---
+
+## Usage
+
+Once installed, you can import the package in Python:
+
+```python
+import ssapy_toolkit as st
+
+from ssapy_toolkit.Orbital_Mechanics import keplerian
+from ssapy_toolkit.Plots import orbit_plot
+```
+
+More detailed examples can be found in the `demos/` directory.
+
+---
+
+## Development
+
+To run the test suite:
+
+```bash
+pytest demos
+```
+
+Code formatting and linting are handled via `ruff` (see `pyproject.toml` for configuration).
+
+---
+
+## Documentation
+
+Project documentation is built with Sphinx and hosted on Read the Docs.
+Once configured, you will be able to find the latest documentation at:
+
+https://ssapy-toolkit.readthedocs.io
+
+To build the docs locally (after installing dev dependencies):
+
+```bash
+cd docs
+make html
+```
+
+The built HTML files will be in `docs/_build/html/`.
+
+---
+
+## License
+
+This project is licensed under the BSD 3-Clause License. See the `LICENSE` file for details.

ssapy_toolkit-1.0.0/README.md

@@ -0,0 +1,81 @@
+# SSAPy Toolkit
+
+**SSAPy Toolkit** (Python package: `ssapy_toolkit`) is a collection of extensions for the SSAPy ecosystem, providing tools for orbital mechanics, plotting, and data IO to support research and engineering workflows.
+
+SSAPy itself is a fast, flexible, high-fidelity orbital modeling and analysis tool for orbits spanning from low-Earth orbit into the cislunar regime. It supports rich satellite definitions, multiple element types and coordinate frames, configurable force models (Earth and lunar gravity, radiation pressure, drag, planetary perturbations, maneuvers), a variety of integrators, Monte Carlo and UQ workflows, and extensive ground/space observer and plotting capabilities. See the SSAPy repository for full details:
+
+https://github.com/llnl/SSAPy/tree/main
+
+---
+
+## Features
+- Utility functions for orbital mechanics and astrodynamics
+- Coordinate transforms and time conversions
+- Data IO helpers for HDF5, CSV, JSON, and more
+- Plotting helpers for orbits, ground tracks, and dashboards
+
+---
+
+## Installation
+
+SSAPy Toolkit is a standard Python package.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install -e .[dev]
+```
+
+This installs the package in editable mode along with development dependencies (testing, linting, docs tools, etc.).
+
+---
+
+## Usage
+
+Once installed, you can import the package in Python:
+
+```python
+import ssapy_toolkit as st
+
+from ssapy_toolkit.Orbital_Mechanics import keplerian
+from ssapy_toolkit.Plots import orbit_plot
+```
+
+More detailed examples can be found in the `demos/` directory.
+
+---
+
+## Development
+
+To run the test suite:
+
+```bash
+pytest demos
+```
+
+Code formatting and linting are handled via `ruff` (see `pyproject.toml` for configuration).
+
+---
+
+## Documentation
+
+Project documentation is built with Sphinx and hosted on Read the Docs.
+Once configured, you will be able to find the latest documentation at:
+
+https://ssapy-toolkit.readthedocs.io
+
+To build the docs locally (after installing dev dependencies):
+
+```bash
+cd docs
+make html
+```
+
+The built HTML files will be in `docs/_build/html/`.
+
+---
+
+## License
+
+This project is licensed under the BSD 3-Clause License. See the `LICENSE` file for details.

ssapy_toolkit-1.0.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ssapy-toolkit"
+version = "1.0.0"
+description = "SSAPy Toolkit: extensions for orbital mechanics, plotting, and data IO"
+authors = [
+  { name = "Travis R. Yeager", email = "yeagerastro@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+keywords = ["orbital-mechanics", "astrodynamics", "visualization", "utilities"]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Astronomy",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+
+dependencies = [
+  "astropy",
+  "astroquery",
+  "corner",
+  "emcee",
+  "gitpython",
+  "h5py",
+  "imageio",
+  "imageio-ffmpeg",
+  "ipykernel",
+  "ipympl",
+  "ipython",
+  "ipytree",
+  "ipyvolume",
+  "jplephem",
+  "llnl-ssapy",
+  "lmfit",
+  "matplotlib",
+  "mpmath",
+  "nexusformat",
+  "npy-append-array",
+  "numpy",
+  "opencv-python",
+  "pandas",
+  "pillow",
+  "psutil",
+  "pyerfa",
+  "PyPDF2",
+  "rebound",
+  "regex",
+  "requests",
+  "scikit-learn",
+  "seaborn",
+  "selenium",
+  "sympy",
+  "tqdm",
+  "spacetrack",
+  "vg",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-mpi",
+  "sphinx",
+  "sphinx-rtd-theme",
+  "myst-parser<4.0.0",
+  "ruff",
+  "build",
+  "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/llnl/SSAPy-Toolkit"
+Repository = "https://github.com/llnl/SSAPy-Toolkit"
+Issues = "https://github.com/llnl/SSAPy-Toolkit/issues"
+Documentation = "https://ssapy-toolkit.readthedocs.io/"
+
+[tool.setuptools]
+packages = { find = { where = ["."], include = ["ssapy_toolkit*"] } }

ssapy_toolkit-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ssapy_toolkit-1.0.0/ssapy_toolkit/Accelerations/__init__.py

@@ -0,0 +1,18 @@
+"""Acceleration models and utilities for orbit propagation."""
+
+import importlib
+import os
+
+# Get the directory of the current file
+sub_dir = os.path.dirname(__file__)
+
+# Loop through all Python files in this directory and import their functions
+for filename in os.listdir(sub_dir):
+    if filename.endswith(".py") and filename != "__init__.py":
+        module_name = f"{__name__}.{filename[:-3]}"
+        module = importlib.import_module(module_name)
+
+        # Add all attributes of the module to the package namespace
+        for attr in dir(module):
+            if not attr.startswith("_"):  # Avoid internal attributes
+                globals()[attr] = getattr(module, attr)

ssapy_toolkit-1.0.0/ssapy_toolkit/Accelerations/accel_add.py

@@ -0,0 +1,26 @@
+import numpy as np
+
+
+def accel_add(*accel_funcs):
+    """
+    Returns a function that sums multiple acceleration functions.
+
+    Parameters
+    ----------
+    accel_funcs : list of functions
+        Each must take (r) or (r, t) depending on your usage.
+
+    Returns
+    -------
+    combined : function
+        A function that evaluates and sums all input accelerations.
+    """
+    def combined(r, t=None):
+        total = np.zeros(3)
+        for f in accel_funcs:
+            try:
+                total += f(r, t)
+            except TypeError:
+                total += f(r)
+        return total
+    return combined

ssapy_toolkit-1.0.0/ssapy_toolkit/Accelerations/accel_circularize.py

@@ -0,0 +1,88 @@
+# ssapy_toolkit/Accelerations/accel_circularize.py
+
+import numpy as np
+from ..constants import EARTH_MU, EARTH_RADIUS  # [56]
+
+_orbit_achieved = False  # global variable to track circularization
+
+
+def reset_orbit_status():
+    """Reset the internal latch so circularization thrust can be used again."""
+    global _orbit_achieved
+    _orbit_achieved = False
+
+
+def accel_to_circular(r, v, t=None, *, thrust, tol=10.0, min_altitude=100e3):
+    """
+    Acceleration command that steers (r, v) toward a circular orbit at radius |r|.
+
+    Designed to be passed into leapfrog(..., accels=[...]) where leapfrog may call
+    accelerations as f(r,v,t) (t is accepted but not required here).
+
+    Parameters
+    ----------
+    r : array_like, shape (3,)
+        Position vector (m).
+    v : array_like, shape (3,)
+        Velocity vector (m/s).
+    t : optional
+        Time (ignored; present for integrator compatibility).
+    thrust : float
+        Magnitude of available acceleration (m/s^2).
+    tol : float, optional
+        Convergence tolerance on ||v_target - v|| (m/s). Default 10.
+    min_altitude : float, optional
+        Minimum altitude above Earth's surface to allow control (m). Default 100 km.
+
+    Returns
+    -------
+    a : ndarray, shape (3,)
+        Acceleration command (m/s^2), or zeros if converged/disabled.
+    """
+    global _orbit_achieved
+
+    if _orbit_achieved:
+        return np.zeros(3, dtype=float)
+
+    r = np.asarray(r, dtype=float).reshape(3)
+    v = np.asarray(v, dtype=float).reshape(3)
+
+    r_norm = np.linalg.norm(r)
+    if r_norm == 0.0 or thrust == 0.0:
+        return np.zeros(3, dtype=float)
+
+    if r_norm < EARTH_RADIUS + float(min_altitude):
+        return np.zeros(3, dtype=float)
+
+    # Unit radial direction
+    r_hat = r / r_norm
+
+    # Tangential velocity component
+    v_r = float(np.dot(v, r_hat))
+    v_t_vec = v - v_r * r_hat
+    v_t = np.linalg.norm(v_t_vec)
+
+    if v_t > 0.0:
+        t_hat = v_t_vec / v_t
+    else:
+        # Fallback if velocity is purely radial: pick a consistent tangential direction
+        t_hat = np.cross(np.array([0.0, 0.0, 1.0]), r_hat)
+        n = np.linalg.norm(t_hat)
+        if n == 0.0:
+            return np.zeros(3, dtype=float)
+        t_hat /= n
+
+    # Circular speed at current radius
+    v_circ = np.sqrt(EARTH_MU / r_norm)
+
+    # Desired circular velocity vector (purely tangential)
+    v_target = v_circ * t_hat
+
+    dv = v_target - v
+    dv_norm = np.linalg.norm(dv)
+
+    if dv_norm <= float(tol) or dv_norm == 0.0:
+        _orbit_achieved = True
+        return np.zeros(3, dtype=float)
+
+    return float(thrust) * (dv / dv_norm)

ssapy_toolkit-1.0.0/ssapy_toolkit/Accelerations/accel_deltav.py

@@ -0,0 +1,50 @@
+import numpy as np
+
+def accel_deltav(dv: float, thrust_accel: float, center_idx: int, dt: float = 1.0) -> dict:
+    """
+    Build a Δv-based along-track accel profile centered at a given step.
+
+    Parameters
+    ----------
+    dv : float
+        Signed total Δv to deliver (m/s). (Only its sign matters.)
+    thrust_accel : float
+        Available constant acceleration magnitude (m/s²). Must be > 0.
+    center_idx : int
+        Index in your time array where the burn is centered.
+    dt : float, optional
+        Uniform timestep between your indices (s). Defaults to 1 s.
+
+    Returns
+    -------
+    profile : dict
+        A dict with keys:
+          - 'thrust' : signed acceleration (m/s²)
+          - 'start'  : start index (int)
+          - 'end'    : end index (int)
+        which you can pass directly to `leapfrog(..., velocity=profile)`.
+    """
+    if thrust_accel <= 0:
+        raise ValueError("`thrust_accel` must be positive")
+    if dt <= 0:
+        raise ValueError("`dt` must be positive")
+
+    # total burn time (s) required for |Δv|
+    burn_time = abs(dv) / thrust_accel
+
+    # number of steps (round to nearest int, minimum 1)
+    steps = max(1, int(round(burn_time / dt)))
+
+    # center the burn on center_idx
+    half = steps // 2
+    start = center_idx - half
+    end = start + steps  # ensures end - start == steps
+
+    # signed acceleration to match dv's sign
+    signed_accel = thrust_accel * np.sign(dv)
+
+    return {
+        "thrust": signed_accel,
+        "start": start,
+        "end": end,
+    }

ssapy_toolkit-1.0.0/ssapy_toolkit/Accelerations/accel_deltav_vector.py

@@ -0,0 +1,39 @@
+import numpy as np
+
+
+def accel_deltav_vector(dv, duration):
+    """
+    Compute the constant acceleration vector needed to achieve a given Δv in a set time.
+
+    Parameters
+    ----------
+    dv : array_like, shape (3,)
+        Desired change in velocity vector (m/s).
+    duration : float
+        Time over which to apply the acceleration (s).
+
+    Returns
+    -------
+    thrust : float
+        Magnitude of the required acceleration (m/s²).
+    direction : ndarray, shape (3,)
+        Unit vector indicating acceleration direction.
+    a_vec : ndarray, shape (3,)
+        Acceleration vector (m/s²) that, when applied constantly over `duration`, yields `dv`.
+
+    Raises
+    ------
+    ValueError
+        If `duration` is zero or negative.
+    """
+    dv = np.asarray(dv, dtype=float)
+    if duration <= 0:
+        raise ValueError("Duration must be positive and non-zero.")
+    dv_norm = np.linalg.norm(dv)
+    if dv_norm == 0:
+        return 0.0, np.zeros(3), np.zeros(3)
+
+    thrust = dv_norm / duration
+    direction = dv / dv_norm
+    a_vec = thrust * direction
+    return thrust, direction, a_vec