Skip to content
Back to skills

Keplerian Elements

ASecurity

Use when you must compute classical orbital elements from a position and velocity state vector: derive the specific angular momentum, node vector and eccentricity vector, then convert to semimajor axis, eccentricity, inclination, right ascension of the ascending node (RAAN), argument of periapsis and true anomaly, and derive the orbital period with periapsis and apoapsis radii for an elliptical Earth orbit. Handles circular and equatorial degenerate cases with documented conventions and raise...

  • 2 stars
  • 0 votes
  • 0 copies
  • 2 views
  • Added September 27, 2026
ai-agentspythonangularnode

Works with

  • claude code
  • cli

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned September 27, 2026

npx -y skills add ashfordeOU/aero-agent-skills --skill keplerian-elements --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Keplerian Elements?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Keplerian Elements
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/ashfordeou-keplerian-elements/badge)](https://www.skillsdirectory.com/skills/ashfordeou-keplerian-elements)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: keplerian-elements
description: "Use when you must compute classical orbital elements from a position and velocity state vector: derive the specific angular momentum, node vector and eccentricity vector, then convert to semimajor axis, eccentricity, inclination, right ascension of the ascending node (RAAN), argument of periapsis and true anomaly, and derive the orbital period with periapsis and apoapsis radii for an elliptical Earth orbit. Handles circular and equatorial degenerate cases with documented conventions and raises on parabolic or hyperbolic inputs. Uses Earth gravitational parameter 398600.4418 km^3/s^2 by default. Trigger: keplerian elements, orbital elements, rv2coe, state vector, raan, argument of periapsis, true anomaly, semimajor axis, eccentricity, inclination, orbital period, periapsis, apoapsis."
license: Apache-2.0
compliance: STANDARDS-REF
standards:
  - id: ecss
    reference-only: true
gated: false
domain: space-systems
pack: space-systems
compatibility: "agentskills.io SKILL.md; any SKILL.md host (Claude Code, Hermes, OpenClaw)"
metadata:
  domain: space-systems
  subdomain: orbit-mechanics
  tags: [keplerian-elements, orbital-elements, rv2coe, state-vector, raan, argument-of-periapsis, true-anomaly, inclination, semimajor-axis, eccentricity, orbital-period, periapsis, apoapsis]
  version: 0.1.0
  author: Aero Agent Skills
---

# Keplerian Elements (space-systems/orbit-mechanics/keplerian-elements)

Use when the task is converting a spacecraft position and velocity
state vector into the classical (keplerian) orbital elements:
semimajor axis, eccentricity, inclination, right ascension of the
ascending node (RAAN), argument of periapsis, and true anomaly, plus
the orbital period and the periapsis and apoapsis radii of an
elliptical orbit.

## Domain quick reference

- Input: position r (km) and velocity v (km/s) in an inertial frame,
  gravitational parameter mu in km^3/s^2 (default 398600.4418, Earth).
- Specific angular momentum: h = r x v (km^2/s).
- Node vector: n = k x h with k = (0, 0, 1); zero when equatorial.
- Eccentricity vector: e_vec = (v x h) / mu - r / |r|; e = |e_vec|.
- Specific energy: epsilon = v^2 / 2 - mu / |r| (km^2/s^2).
- Semimajor axis: a = -mu / (2 epsilon); parabolic (epsilon ~ 0)
  raises ValueError, hyperbolic returns negative a.
- Inclination: i = acos(h_z / |h|) in radians, range [0, pi].
- RAAN: Omega = atan2(n_y, n_x); convention 0.0 when equatorial.
- Argument of periapsis: omega = acos(n . e_vec / (|n| e)), corrected
  to 2 pi - omega when e_z < 0; equatorial convention
  atan2(e_y, e_x); circular convention 0.0.
- True anomaly: nu = acos(e_vec . r / (e |r|)), corrected to
  2 pi - nu when r . v < 0; circular convention measured from the
  node vector; circular equatorial atan2(r_y, r_x).
- Orbital period: T = 2 pi sqrt(a^3 / mu) in seconds; elliptical
  orbits only (raises ValueError for a <= 0).
- Periapsis and apoapsis radii: rp = a (1 - e), ra = a (1 + e);
  elliptical orbits only (raises ValueError for e >= 1).

## Workflow

1. Validate r, v and mu; raise ValueError on non-finite entries,
   wrong length, zero radius or mu <= 0.
2. Compute h with specific_angular_momentum and check |h| > 0,
   else ValueError for a rectilinear (radial) trajectory.
3. Compute n, e_vec, epsilon, then a, e, i and Omega with the
   standalone helpers.
4. Apply the circular and equatorial conventions when computing
   omega and nu with argument_of_periapsis and true_anomaly.
5. Compute T, rp and ra with orbital_period and
   periapsis_apoapsis_radii for elliptical orbits.
6. Pack the full solution with keplerian_elements(r, v, mu) and
   check the returned dict for consistency.

## Pitfalls

- Feeding degrees where radians are expected; every angle out is
  radians.
- Skipping the 2 pi corrections: acos alone is sign-ambiguous, the
  r . v test (for nu) and the e_z test (for omega) resolve it.
- Calling orbital_period or periapsis_apoapsis_radii on parabolic or
  hyperbolic orbits: they raise ValueError instead of returning
  nonsense.
- Forgetting that e ~ 0 (circular) or |n| ~ 0 (equatorial) makes
  acos(0/0) undefined, hence the documented conventions.
- Mixing units, e.g. r in km with v in m/s, silently corrupts every
  element.

## Behavior contract (gate 3)

The rv2coe logic is exercised by the gate 3 contract test:
scripts/test_keplerian.py against scripts/keplerian_logic.py (stdlib
unittest, offline). Run: python3 scripts/test_keplerian.py

## Compliance

- Standards referenced, not reproduced: ECSS series text is copyright
  ESA and freely downloadable (standards-map.yaml); the two-body
  rv2coe conversion is common astrodynamics, summary-only.
- compliance: STANDARDS-REF, gated: false.

Files in this skill

  • SKILL.md4.6 KB
  • scripts/keplerian_logic.py8.3 KB
  • scripts/test_keplerian.py11.1 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.