urania 0.0.1__tar.gz

urania-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+examples/*.png

urania-0.0.1/LICENSE

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

urania-0.0.1/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: urania
+Version: 0.0.1
+Summary: An astrodynamics library that computes, shows and explains
+Project-URL: Homepage, https://github.com/dandmadp/urania
+Project-URL: Source, https://github.com/dandmadp/urania
+Project-URL: Issues, https://github.com/dandmadp/urania/issues
+Author: dandmadp
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astrodynamics,cubesat,hohmann,orbit,orbital mechanics,satellite,sgp4,tle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: astropy>=5.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: sgp4>=2.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# urania
+
+**An astrodynamics library that computes, shows and explains**
+
+urania is a Python library for people who are not professionals but want to compute orbits seriously: CubeSat teams, students, space simulation game players. Every result records the model and assumptions it was computed with, and `.explain()` walks through the formulas and intermediate values step by step.
+
+> Status: MVP in development (v0.0.1). Design: [SPEC.md](https://github.com/dandmadp/urania/blob/main/SPEC.md). Design decisions: [docs/DECISIONS.md](https://github.com/dandmadp/urania/blob/main/docs/DECISIONS.md).
+
+## Installation
+
+Not on PyPI yet, so install from source. Python 3.10 or newer.
+
+```bash
+git clone https://github.com/dandmadp/urania.git
+cd urania
+python -m venv .venv
+.venv\Scripts\activate          # macOS/Linux: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start
+
+The Δv needed to go from the ISS orbit to geostationary orbit (GEO):
+
+```python
+import urania as ur
+
+transfer = ur.ISS.transfer_to(ur.GEO)
+print(transfer)                    # Transfer(hohmann, Δv=4.7797 km/s, tof=5.295 h, 2 burns)
+print(transfer.explain())          # formulas, intermediate speeds, Δv per burn, assumptions
+transfer.plot()                    # 2D plot (matplotlib)
+```
+
+Part of the `explain()` output:
+
+```text
+3. Burn 1 (r₁)
+   v₁ = √(μ/r₁) = 7.6573 km/s  (initial circular orbit)
+   v₂ = √(μ(2/r₁ − 1/a_t)) = 10.0492 km/s  (transfer ellipse)
+   combined with plane change α = 2.8913°
+   Δv = √(v₁² + v₂² − 2 v₁ v₂ cos α) = 2.4325 km/s
+```
+
+## Creating orbits
+
+Pass values with units (astropy), or plain numbers, which are taken as SI (m, m/s, rad).
+
+```python
+import astropy.units as u
+import urania as ur
+
+leo = ur.Orbit.circular(ur.Earth, 500 * u.km, inc=97.4 * u.deg)
+ell = ur.Orbit.from_elements(ur.Earth, a=8000 * u.km, ecc=0.1, inc=30 * u.deg,
+                             raan=40 * u.deg, argp=60 * u.deg, nu=0 * u.deg)
+sv = ur.Orbit.from_vectors(ur.Earth, [6524.834, 6862.875, 6448.296] * u.km,
+                           [4.901327, 5.533756, -1.976341] * u.km / u.s)
+
+print(sv.a, sv.ecc, sv.period)     # results are SI numbers: m, -, s
+print(sv.explain())                # how the elements follow from the state vector
+```
+
+Presets: bodies `Sun`, `Earth`, `Moon`, `Mars`; orbits `LEO` (500 km), `ISS` (420 km, 51.64°), `SSO` (700 km sun-synchronous), `GEO`.
+
+## Propagation
+
+Choose the fidelity: `"twobody"` (0) → `"j2"` (1) → `"j2+drag"` (2). The original object is unchanged; a new `Trajectory` is returned.
+
+```python
+import astropy.units as u
+import urania as ur
+
+cubesat = dict(cd=2.2, area=0.03 * u.m**2, mass=4.0 * u.kg)
+start = ur.Orbit.circular(ur.Earth, 400 * u.km, inc=51.6 * u.deg)
+
+tr = start.propagate(days=3, model="j2+drag", **cubesat)
+print(tr.final)                    # orbit after 3 days
+print(tr.info.assumptions)         # model and assumptions used
+tr.plot(kind="altitude")           # altitude with an orbit-averaged line
+```
+
+You can inject environment data yourself: a constant, a function `f(r, t)`, or an `Environment` object.
+
+```python
+import urania as ur
+
+start = ur.Orbit.circular(ur.Earth, 400e3)
+kw = dict(days=1, model="drag", area=0.03, mass=4.0)
+
+start.propagate(density=3e-12, **kw)                                       # constant [kg/m³]
+start.propagate(density=lambda r, t: 2 * ur.Earth.atmosphere(r, t), **kw)  # function
+```
+
+## Maneuvers
+
+```python
+import astropy.units as u
+import urania as ur
+
+ur.LEO.transfer_to(ur.GEO)                                   # Hohmann transfer
+far = ur.Orbit.circular(ur.Earth, 150000 * u.km)
+ur.LEO.transfer_to(far, "bielliptic", rb=300000 * u.km)     # bi-elliptic transfer
+ur.ISS.transfer_to(ur.GEO, plane_split=0)                    # whole plane change at apoapsis
+```
+
+When the planes differ, burns happen at the line of nodes, and by default a Hohmann transfer splits the plane change optimally between its two burns.
+
+## TLE
+
+```python
+import urania as ur
+
+iss = ur.TLEOrbit.from_text("""ISS (ZARYA)
+1 25544U 98067A   19343.69339541  .00001764  00000-0  38792-4 0  9991
+2 25544  51.6439 211.2001 0007417  17.6667  85.6398 15.50103472202482""")
+
+sgp4 = iss.propagate(days=1)                          # SGP4 only
+mine = iss.to_orbit().propagate(days=1, model="j2")   # extract the state, propagate with urania
+```
+
+TLE elements are SGP4-specific mean elements, so they are kept separate from `Orbit`. The frame is SGP4's TEME, used as is.
+
+## Accuracy and validation
+
+| What | Reference | Result |
+|---|---|---|
+| Element conversion | Curtis examples 4.3, 4.7 / Vallado example 2-5 | matches to the textbook's printed precision |
+| Kepler's equation and propagation | Vallado examples 2-1, 2-3, 2-4 | within 1e-9 rad / 1 m |
+| Hohmann and bi-elliptic transfers | Vallado examples 6-1, 6-2 | Δv within 1 mm/s |
+| J2 secular drift | analytic nodal rate | within 1% over 10 days |
+| Drag decay | analytic circular decay da/dt = −ρB√(μa) | within 1% |
+| SGP4 wrapper | Vallado SGP4 verification set (satellite 00005) | within 1e-6 km |
+| urania propagator vs SGP4 | real ISS TLE (2019-12-09), J2 model | at most 2.34 km over 24 hours |
+| NASA GMAT R2026a, two-body | 1 day, RK89 | at most 0.009 m |
+| NASA GMAT R2026a, J2 | 7 days, 420 km, 51.64° | at most 3.3 m (144 m without the true pole, see below) |
+| NASA GMAT R2026a, J2 + drag | 3 days, 400 km, exponential atmosphere | at most 3.3 m (73 m without the true pole) |
+
+SGP4 itself is accurate to about 1 km near epoch, so the SGP4 comparison is a sanity check rather than precise validation. Precise validation comes from the GMAT comparison ([validation/gmat](https://github.com/dandmadp/urania/blob/main/validation/gmat), [tests/test_gmat.py](https://github.com/dandmadp/urania/blob/main/tests/test_gmat.py)).
+
+GMAT evaluates J2 and the atmosphere about Earth's true spin axis, which at the J2000 epoch is 7.69" away from the J2000 z axis. urania uses the frame's z axis as the spin axis. The small figures above compare both in a frame whose z axis is the true pole; the larger figures in parentheses are the direct comparison in the J2000 frame.
+
+## Limitations (MVP)
+
+- Perturbations: J2 and atmospheric drag. Lunar/solar perturbations, solar radiation pressure and higher-order gravity come later.
+- Atmosphere: Vallado's exponential model (mean solar activity), with height above the reference ellipsoid. Real density varies several-fold with solar activity.
+- Maneuvers: impulsive transfers between circular orbits. Rendezvous (phasing) and interplanetary transfers come later.
+- Time: TDB internally. UTC input goes through `Epoch.from_astropy()`.
+- Frames: fixed inertial axes (precession and nutation ignored). TLEs use TEME as is.
+- Plots: 2D only.
+
+## Examples
+
+- [examples/quickstart.py](https://github.com/dandmadp/urania/blob/main/examples/quickstart.py): ISS → GEO transfer
+- [examples/cubesat_decay.py](https://github.com/dandmadp/urania/blob/main/examples/cubesat_decay.py): 3U CubeSat decay and sensitivity to atmospheric density
+- [examples/tle_vs_propagator.py](https://github.com/dandmadp/urania/blob/main/examples/tle_vs_propagator.py): comparison with SGP4 using a real ISS TLE
+
+## License
+
+MIT

urania-0.0.1/README.md

@@ -0,0 +1,159 @@
+# urania
+
+**An astrodynamics library that computes, shows and explains**
+
+urania is a Python library for people who are not professionals but want to compute orbits seriously: CubeSat teams, students, space simulation game players. Every result records the model and assumptions it was computed with, and `.explain()` walks through the formulas and intermediate values step by step.
+
+> Status: MVP in development (v0.0.1). Design: [SPEC.md](https://github.com/dandmadp/urania/blob/main/SPEC.md). Design decisions: [docs/DECISIONS.md](https://github.com/dandmadp/urania/blob/main/docs/DECISIONS.md).
+
+## Installation
+
+Not on PyPI yet, so install from source. Python 3.10 or newer.
+
+```bash
+git clone https://github.com/dandmadp/urania.git
+cd urania
+python -m venv .venv
+.venv\Scripts\activate          # macOS/Linux: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick start
+
+The Δv needed to go from the ISS orbit to geostationary orbit (GEO):
+
+```python
+import urania as ur
+
+transfer = ur.ISS.transfer_to(ur.GEO)
+print(transfer)                    # Transfer(hohmann, Δv=4.7797 km/s, tof=5.295 h, 2 burns)
+print(transfer.explain())          # formulas, intermediate speeds, Δv per burn, assumptions
+transfer.plot()                    # 2D plot (matplotlib)
+```
+
+Part of the `explain()` output:
+
+```text
+3. Burn 1 (r₁)
+   v₁ = √(μ/r₁) = 7.6573 km/s  (initial circular orbit)
+   v₂ = √(μ(2/r₁ − 1/a_t)) = 10.0492 km/s  (transfer ellipse)
+   combined with plane change α = 2.8913°
+   Δv = √(v₁² + v₂² − 2 v₁ v₂ cos α) = 2.4325 km/s
+```
+
+## Creating orbits
+
+Pass values with units (astropy), or plain numbers, which are taken as SI (m, m/s, rad).
+
+```python
+import astropy.units as u
+import urania as ur
+
+leo = ur.Orbit.circular(ur.Earth, 500 * u.km, inc=97.4 * u.deg)
+ell = ur.Orbit.from_elements(ur.Earth, a=8000 * u.km, ecc=0.1, inc=30 * u.deg,
+                             raan=40 * u.deg, argp=60 * u.deg, nu=0 * u.deg)
+sv = ur.Orbit.from_vectors(ur.Earth, [6524.834, 6862.875, 6448.296] * u.km,
+                           [4.901327, 5.533756, -1.976341] * u.km / u.s)
+
+print(sv.a, sv.ecc, sv.period)     # results are SI numbers: m, -, s
+print(sv.explain())                # how the elements follow from the state vector
+```
+
+Presets: bodies `Sun`, `Earth`, `Moon`, `Mars`; orbits `LEO` (500 km), `ISS` (420 km, 51.64°), `SSO` (700 km sun-synchronous), `GEO`.
+
+## Propagation
+
+Choose the fidelity: `"twobody"` (0) → `"j2"` (1) → `"j2+drag"` (2). The original object is unchanged; a new `Trajectory` is returned.
+
+```python
+import astropy.units as u
+import urania as ur
+
+cubesat = dict(cd=2.2, area=0.03 * u.m**2, mass=4.0 * u.kg)
+start = ur.Orbit.circular(ur.Earth, 400 * u.km, inc=51.6 * u.deg)
+
+tr = start.propagate(days=3, model="j2+drag", **cubesat)
+print(tr.final)                    # orbit after 3 days
+print(tr.info.assumptions)         # model and assumptions used
+tr.plot(kind="altitude")           # altitude with an orbit-averaged line
+```
+
+You can inject environment data yourself: a constant, a function `f(r, t)`, or an `Environment` object.
+
+```python
+import urania as ur
+
+start = ur.Orbit.circular(ur.Earth, 400e3)
+kw = dict(days=1, model="drag", area=0.03, mass=4.0)
+
+start.propagate(density=3e-12, **kw)                                       # constant [kg/m³]
+start.propagate(density=lambda r, t: 2 * ur.Earth.atmosphere(r, t), **kw)  # function
+```
+
+## Maneuvers
+
+```python
+import astropy.units as u
+import urania as ur
+
+ur.LEO.transfer_to(ur.GEO)                                   # Hohmann transfer
+far = ur.Orbit.circular(ur.Earth, 150000 * u.km)
+ur.LEO.transfer_to(far, "bielliptic", rb=300000 * u.km)     # bi-elliptic transfer
+ur.ISS.transfer_to(ur.GEO, plane_split=0)                    # whole plane change at apoapsis
+```
+
+When the planes differ, burns happen at the line of nodes, and by default a Hohmann transfer splits the plane change optimally between its two burns.
+
+## TLE
+
+```python
+import urania as ur
+
+iss = ur.TLEOrbit.from_text("""ISS (ZARYA)
+1 25544U 98067A   19343.69339541  .00001764  00000-0  38792-4 0  9991
+2 25544  51.6439 211.2001 0007417  17.6667  85.6398 15.50103472202482""")
+
+sgp4 = iss.propagate(days=1)                          # SGP4 only
+mine = iss.to_orbit().propagate(days=1, model="j2")   # extract the state, propagate with urania
+```
+
+TLE elements are SGP4-specific mean elements, so they are kept separate from `Orbit`. The frame is SGP4's TEME, used as is.
+
+## Accuracy and validation
+
+| What | Reference | Result |
+|---|---|---|
+| Element conversion | Curtis examples 4.3, 4.7 / Vallado example 2-5 | matches to the textbook's printed precision |
+| Kepler's equation and propagation | Vallado examples 2-1, 2-3, 2-4 | within 1e-9 rad / 1 m |
+| Hohmann and bi-elliptic transfers | Vallado examples 6-1, 6-2 | Δv within 1 mm/s |
+| J2 secular drift | analytic nodal rate | within 1% over 10 days |
+| Drag decay | analytic circular decay da/dt = −ρB√(μa) | within 1% |
+| SGP4 wrapper | Vallado SGP4 verification set (satellite 00005) | within 1e-6 km |
+| urania propagator vs SGP4 | real ISS TLE (2019-12-09), J2 model | at most 2.34 km over 24 hours |
+| NASA GMAT R2026a, two-body | 1 day, RK89 | at most 0.009 m |
+| NASA GMAT R2026a, J2 | 7 days, 420 km, 51.64° | at most 3.3 m (144 m without the true pole, see below) |
+| NASA GMAT R2026a, J2 + drag | 3 days, 400 km, exponential atmosphere | at most 3.3 m (73 m without the true pole) |
+
+SGP4 itself is accurate to about 1 km near epoch, so the SGP4 comparison is a sanity check rather than precise validation. Precise validation comes from the GMAT comparison ([validation/gmat](https://github.com/dandmadp/urania/blob/main/validation/gmat), [tests/test_gmat.py](https://github.com/dandmadp/urania/blob/main/tests/test_gmat.py)).
+
+GMAT evaluates J2 and the atmosphere about Earth's true spin axis, which at the J2000 epoch is 7.69" away from the J2000 z axis. urania uses the frame's z axis as the spin axis. The small figures above compare both in a frame whose z axis is the true pole; the larger figures in parentheses are the direct comparison in the J2000 frame.
+
+## Limitations (MVP)
+
+- Perturbations: J2 and atmospheric drag. Lunar/solar perturbations, solar radiation pressure and higher-order gravity come later.
+- Atmosphere: Vallado's exponential model (mean solar activity), with height above the reference ellipsoid. Real density varies several-fold with solar activity.
+- Maneuvers: impulsive transfers between circular orbits. Rendezvous (phasing) and interplanetary transfers come later.
+- Time: TDB internally. UTC input goes through `Epoch.from_astropy()`.
+- Frames: fixed inertial axes (precession and nutation ignored). TLEs use TEME as is.
+- Plots: 2D only.
+
+## Examples
+
+- [examples/quickstart.py](https://github.com/dandmadp/urania/blob/main/examples/quickstart.py): ISS → GEO transfer
+- [examples/cubesat_decay.py](https://github.com/dandmadp/urania/blob/main/examples/cubesat_decay.py): 3U CubeSat decay and sensitivity to atmospheric density
+- [examples/tle_vs_propagator.py](https://github.com/dandmadp/urania/blob/main/examples/tle_vs_propagator.py): comparison with SGP4 using a real ISS TLE
+
+## License
+
+MIT

urania-0.0.1/SPEC.md

@@ -0,0 +1,119 @@
+# urania — Astrodynamics Library Design Specification (MVP)
+
+> **An astrodynamics library that computes, shows and explains**
+> Package name: **urania** (after Urania, the muse of astronomy). Confirmed free on PyPI as of 2026-10-07. Reserve the name with an empty package when work starts.
+
+## 1. Purpose and target users
+
+- Audience: university clubs (CubeSat teams, etc.), students, space simulation game players, educational content creators, space enthusiasts
+- What they share: not professionals, but serious about understanding and computing things in space
+- Accuracy target: at least textbook level, good enough for a CubeSat team's practical calculations. Space-agency level (high-order gravity fields, etc.) is not a goal
+- Every result must be verifiable, and must record which assumptions and models produced it
+
+## 2. Core design principles
+
+1. **The object API is the official entry point**
+   - Documentation, README and tutorial examples are all written with the object API
+   - Example: `ISS.orbit.transfer_to(GEO).plot()`
+2. **A functional core inside**
+   - Actual computation is implemented only in pure functions in `urania.core`
+   - Object methods only call core functions (one implementation, in one place)
+   - Core functions must also work with plain numbers (SI) → for checking against textbook examples
+3. **Immutable objects**
+   - All major objects are immutable, e.g. `dataclass(frozen=True)`
+   - `orbit.propagate(...)` returns a new object without changing the original
+4. **Units: SI internally, conversion only at the boundary**
+   - Internal computation uses only m, kg, s, K, W
+   - Input: values with units (choose astropy.units or pint and record why) are converted; plain numbers are taken as SI
+   - Output: SI by default, converted on request
+5. **Time: always TDB seconds internally (seconds elapsed since an epoch)**
+   - UTC/TAI conversion comes after the MVP, but time is encapsulated in one type so it can be added later
+6. **Environment factors are injected as arguments**
+   - The library provides the computational framework; the user supplies environment data (radiation, solar flux, etc.)
+   - Three forms are accepted: constant / `f(position, t)` function / `Environment` object
+   - Internally a constant is wrapped as "a function that always returns the same value", so there is one form
+   - The MVP does not implement environment models themselves, only this injection interface
+7. **Selectable fidelity levels**
+   - 0: two-body / 1: +J2 / 2: +atmospheric drag (MVP scope)
+   - 3: +lunar/solar perturbations / 4: +solar radiation pressure, high-order gravity (after the MVP)
+   - Example: `orbit.propagate(days=30, model="j2+drag")`
+8. **Result metadata**
+   - Result objects keep the model, integrator, tolerances and key assumptions used
+9. **Explanation and visualization**
+   - `.explain()`: prints the formulas, assumptions and intermediate values step by step
+   - `.plot()`: 2D orbit plot (matplotlib)
+
+## 3. MVP scope
+
+### Included
+- **Objects**
+  - `Body`: mass, radius, μ, J2, hook for an atmosphere model
+  - `Orbit`: orbital elements ↔ position/velocity (state vector) conversion
+  - `Transfer`: maneuver result (total Δv, duration, list of burns)
+  - `TLEOrbit`: TLE-based orbit (see TLE below)
+- **Presets**
+  - Bodies: Sun, Earth, Moon, Mars (the other planets if time allows)
+  - Orbits: representative orbits such as `LEO`, `ISS`, `GEO`, `SSO`
+- **Orbit propagation**: fidelity levels 0 to 2
+  - Keep drag simple, around an exponential atmosphere model
+  - Integration: adaptive, based on `scipy.integrate.solve_ivp` (e.g. DOP853)
+- **Maneuvers**: Hohmann transfer, bi-elliptic transfer, plane change
+- **TLE support**
+  - A thin wrapper around the `sgp4` package
+  - TLE orbits are propagated only with SGP4 and never mixed with the in-house propagator (separate `TLEOrbit` object)
+  - Provide an explicit path that extracts a state vector and converts it to an `Orbit` when needed
+- **Explanation/visualization**: `.explain()`, `.plot()`
+- **Unit handling, result metadata, environment injection interface**
+
+### Excluded (next version)
+- Environment models such as temperature and radiation
+- Lunar/solar perturbations, JPL ephemeris (DE440) integration
+- Interplanetary transfers, launch window (porkchop) calculations
+- 3D visualization, animation
+- UTC/TAI/TDB conversion
+
+## 4. Validation
+
+- Compare with textbook examples (Curtis, Vallado worked solutions)
+- Compare with NASA GMAT results (reference data stored as test fixtures)
+- Compare SGP4 predictions with the in-house propagator using a real ISS TLE (doubles as an example and a test)
+- Goal: be able to state in the README a figure such as "within ○○ of GMAT", with evidence
+- Test framework: pytest
+
+## 5. Proposed module structure
+
+```
+urania/
+  core/          # pure functions: orbit conversions, Kepler's equation, maneuver formulas
+  bodies.py      # Body, body presets
+  orbits.py      # Orbit, orbit presets
+  propagation/   # force models per fidelity level, integrators
+  maneuvers.py   # Transfer, maneuver calculations
+  tle.py         # TLEOrbit (sgp4 wrapper)
+  environment.py # environment injection interface
+  units.py       # unit conversion boundary
+  time.py        # time representation (internal TDB seconds)
+  viz.py         # plot
+  explain.py     # explain output
+tests/
+examples/
+```
+
+The structure is a proposal; adjust it with a reason if a better layout exists.
+
+## 6. Development order (recommended)
+
+1. core: state vector ↔ orbital elements, Kepler's equation solver + textbook example tests
+2. Unit and time boundary (`units.py`, `time.py`)
+3. `Body`, `Orbit` objects and presets
+4. Propagator: two-body → J2 → drag
+5. Maneuvers (`Transfer`)
+6. `.plot()`, `.explain()`
+7. TLE wrapper
+8. GMAT and TLE comparison tests, README examples
+
+## 7. Working requests
+
+- Make the tests pass at the end of each step before moving on
+- Record design decisions (such as the unit library choice) with a short rationale
+- Show code changes as code blocks containing only the changed parts

urania-0.0.1/docs/DECISIONS.md

@@ -0,0 +1,156 @@
+# Design decisions
+
+## D1. Store orbit size as the semi-latus rectum p, not the semi-major axis a (step 1)
+- a is infinite for a parabola and negative for a hyperbola, which is awkward for a single type.
+- p is positive and finite for every conic. a is provided through the `Elements.a` property.
+
+## D2. Angle conventions for singular orbits (step 1)
+- Equatorial (i ≈ 0, π): raan = 0, reference axis is inertial x.
+- Circular (e ≈ 0): argp = 0, ν is measured from the node (from x if also equatorial).
+- This packs Vallado's true longitude and argument of latitude into the usual six elements without extra fields.
+  Tests guarantee that `coe_to_rv(rv_to_coe(r, v))` is the identity even for singular orbits.
+- Detection tolerances are dimensionless 1e-11 (`CIRCULAR_TOL`, `EQUATORIAL_TOL`).
+
+## D3. Core functions are scalar and `math`-based (step 1)
+- Kepler's equation and anomaly conversions take scalar floats. They are called inside propagation loops,
+  so this avoids numpy array overhead and keeps the code close to the textbook formulas.
+- If vectorization is needed (e.g. bulk sampling for plots), add separate functions.
+
+## D4. The parabolic mean anomaly is Barker's M = D + D³/3 (step 1)
+- So that `mean_to_true`/`true_to_mean` handle all three conic types from the eccentricity alone.
+
+## D5. astropy for units (step 2)
+- UTC/TAI/TDB conversion will be needed after the MVP, and `astropy.time` provides it. With pint we would have to implement time scales ourselves.
+- It is the de facto standard in astronomy and space, so target users are likely familiar with it.
+- Its downsides (install size, Quantity overhead) do not affect computation because units are converted only at the boundary (`units.py`).
+
+## D6. Plain numbers are SI, including angles (step 2)
+- `to_si(30, ANGLE)` is 30 rad. Degrees must be given explicitly as `30 * u.deg`.
+- Making angles an exception would mean two rules and more mistakes.
+
+## D7. Time is one float64 of TDB seconds since J2000 (step 2)
+- Encapsulated in `Epoch(tdb_seconds)`. Over 2000 to 2100 float64 resolves about 1e-7 s, which is under 1 mm
+  of position error at LEO speed (7.8 km/s), enough for the MVP accuracy target.
+- Calendar and JD input is read as TDB. The TDB calendar has no leap seconds, so plain date differences are exact.
+- Other time scales go through `Epoch.from_astropy()`, where astropy converts them. No in-house conversion.
+
+## D8. Body stores μ (GM) instead of mass (step 3)
+- μ is determined directly from orbit observations and is hundreds of thousands of times more accurate than G or M alone (G itself is uncertain to about 2e-5).
+- Mass is provided as the property `Body.mass = μ/G`. Each preset records the source of its constants in `source`.
+
+## D9. An Orbit is defined by its state vector (r, v, epoch) (step 3)
+- The state vector has no singularities for circular, equatorial or parabolic orbits, and matches the propagator's input/output format.
+- Orbital elements are computed once with `cached_property`. The object is immutable, so the cache never goes stale.
+- r and v are copied into read-only arrays. Value comparison of numpy arrays is ambiguous, so `eq=False` (identity).
+
+## D10. The ISS preset is an Orbit (step 3)
+- SPEC's example `ISS.orbit.transfer_to(GEO)` implies a spacecraft object, but spacecraft are not in the MVP.
+  The preset list (LEO, ISS, GEO, SSO) classifies them as orbits, so the form is `ISS.transfer_to(GEO)`.
+- Presets are representative (ISS: 420 km circular, 51.64°). Use a TLE for the actual position.
+- The GEO radius comes from Earth's rotation rate, the SSO inclination from the J2 nodal rate.
+
+## D11. propagate() returns a Trajectory, not an Orbit (step 4)
+- SPEC asks both for "return a new object" and "keep result metadata". Rather than mixing metadata into Orbit,
+  it returns a `Trajectory` with the time series (t, r, v) and `PropagationInfo` (model, integrator, tolerances, assumptions, stop reason).
+- The final orbit is `trajectory.final`, intermediate ones `orbit_at(i)`. The step 6 `.plot()` uses the time series directly.
+
+## D12. Two-body uses the analytic solution by default, everything else DOP853 (step 4)
+- `method="auto"`: two-body uses the Kepler solution (exact and fast); J2 and drag use `solve_ivp` DOP853.
+  `method="DOP853"` integrates two-body numerically too, which is useful for checking the integrator.
+- Default tolerances rtol=1e-12, atol=1e-8. With rtol=1e-10 an eccentric orbit drifted 51 m from the analytic solution over 10 days;
+  with 1e-12, 0.5 m. Cost is about 1.7x (30 days of ISS j2+drag takes about 5.5 s). Accuracy was chosen for the GMAT comparison.
+- Integration stops on reaching the body's surface and records it in `info.terminated`.
+
+## D13. All environment values become an Environment (step 4)
+- Constant → `Constant`, function f(r, t) → `Function`, `Environment` objects as is. `as_environment()` converts.
+- t is TDB seconds since J2000 (float). It is called every step, so no Epoch object is created.
+- Each Environment has a `description` that goes into the assumptions of the result metadata.
+- Earth's default atmosphere is the Vallado table 8-4 exponential model (`Body.atmosphere`). `density=` overrides it.
+
+## D14. A single propagation.py module instead of a package (step 4)
+- SPEC suggested a `propagation/` package, but at the current size (about 200 lines) one module is easier to read.
+  Force models live in `core/forces.py` and integration in `core/propagate.py`, so propagation.py only assembles them.
+  Split it into a package when fidelity levels 3 and 4 are added.
+- For the same reason atmospheric density has no separate file: the table and density function are in `core/forces.py`,
+  and `ExponentialAtmosphere` is in `environment.py`, since an atmosphere model is an Environment.
+- The two-body analytic solution also stops at the surface, like integration does (brentq between samples finds the impact time).
+
+## Note (resolved in step 6, D19): J2 oscillation of the osculating semi-major axis
+- With J2 the osculating semi-major axis oscillates strongly with a short period (0 to -12 km at ISS altitude). Drag-only decay over 30 days is 2.65 km,
+  but comparing only the endpoints makes it look like 14 km. `Trajectory.explain()` warns and shows the orbit-averaged change; the altitude plot shows a one-orbit moving average.
+
+## D15. Transfers are built from state vectors, not just Δv formulas (step 5)
+- `Transfer` holds `Burn`s with position, epoch and Δv vector, plus the orbit right after each burn (`orbits`).
+  Separately from the magnitude-only formulas (core/maneuvers.py), it adds Δv to the state vector and links burns with the analytic solution.
+  The step 6 plot() uses it directly, and tests cross-check formulas against the vector results.
+- MVP limits: initial and target orbits must be circular (e ≤ 1e-3); phasing within the target orbit (rendezvous) is not matched.
+
+## D16. Burns happen at the node when planes differ; Hohmann plane change is split optimally (step 5)
+- A plane change is only possible at the line of nodes. If the start is not at a node, wait for the next node
+  (`Transfer.coast`). A Hohmann transfer covers half an orbit, so burn 2 happens at the opposite node.
+- Default `plane_split="optimal"`: the split of the plane change between the two burns minimizes total Δv
+  (ISS→GEO: 2.89° at burn 1, about 40 m/s cheaper than doing it all at apoapsis). A number 0 to 1 can be given instead.
+- A bi-elliptic transfer does the whole plane change at the slow intermediate apoapsis.
+
+## D17. pytest uses the importlib import mode (step 5)
+- So core and object-layer tests can share file names, such as `tests/core/test_maneuvers.py` and `tests/test_maneuvers.py`,
+  `--import-mode=importlib` is enabled (the mode pytest recommends).
+
+## D18. matplotlib is imported only when plotting (step 6)
+- urania itself imports faster. Plot labels are in English like the rest of the library (D26).
+
+## D19. explain() returns an Explanation object and cross-checks values with core (step 6)
+- No print side effect. `__repr__` is the text, so it reads directly in a REPL or Jupyter, and print() works too.
+- Intermediate values (circular speed, transfer ellipse speeds, ...) are computed with core functions (`vis_viva`, `combined_dv`, ...).
+  If a Δv recomputed from formulas disagrees with the state-vector Burn, a warning is added (`warnings`).
+
+## D20. Transfer plots unfold each orbit into its own plane (step 6)
+- Projecting onto one plane distorts a target orbit in another plane into an ellipse. All burns lie on the node axis,
+  so with x along the node and (ĥ × x̂) as each orbit's y axis, the unfolded orbits connect.
+- Trajectory plots project onto the initial orbit plane (J2 precession shows in the projection). Altitude plots overlay a one-orbit moving average.
+
+## D21. TLEs are a separate TLEOrbit propagated only with SGP4 (step 7)
+- TLE elements are SGP4-specific mean elements; using them as classical elements is wrong. `TLEOrbit` does not inherit from `Orbit`,
+  and its `propagate()` uses only SGP4. The result is the same `Trajectory`, so plot and explain work as is.
+- The only way to the urania propagator is the explicit `to_orbit(epoch)`, which extracts a state vector.
+- The checksum and the satellite numbers of both lines are checked on construction. On an SGP4 error (decay, ...) the output stops
+  before it and `info.terminated` records it.
+
+## D22. The TLE frame TEME is used as the inertial frame (step 7)
+- TEME → GCRF needs precession and nutation models, outside the MVP scope (no time or frame transformations).
+- The urania propagator also assumes "fixed inertial axes, spin axis = z". TEME's z axis is the true spin axis at that time,
+  so comparing SGP4 with urania is actually consistent. The assumptions list states that the frame is TEME.
+
+## D23. TLE epochs (UTC) ↔ Epoch (TDB) go through astropy (step 7)
+- D7 ruled out in-house time scale conversion. Only the TLE epoch and SGP4 call times go through astropy Time.
+- Gravity constants are WGS72, the TLE convention. An Orbit from `to_orbit()` uses the Earth (WGS 84) constants.
+
+## D24. GMAT comparison uses a script generator and fixed fixtures (step 8)
+- GMAT output cannot be produced in this repository, so it is never made up. `validation/gmat/make_scripts.py` writes GMAT scripts
+  from urania scenarios, and the user commits the results of running them in GMAT (`tests/fixtures/gmat/*.txt`).
+  `tests/test_gmat.py` skips if the fixtures are missing. Tolerances were finalized from the GMAT R2026a results (D27).
+- Conditions are matched to reduce differences: J2000 epoch (zero precession), a test body with GMAT's EGM96 constants, RK89 at 1e-13.
+
+## D25. README code is executed by the tests (step 8)
+- `tests/test_docs.py` runs every ```python block in the README and checks that the Transfer repr written in the README matches.
+  It also runs the example scripts (except cubesat_decay.py, which is slow with two 60-day runs).
+- The urania-vs-SGP4 figure is the maximum measured at 1-minute steps (2.34 km). Looking at only 4 times almost gave 0.98 km.
+
+## D26. Everything in English
+- Code, docstrings, error messages, `explain()` output, tests and documents are all in English, for an international open-source audience.
+  One language avoids keeping two versions in sync. This replaces the earlier Korean-docstring rule and the
+  "explain() text is Korean" part of D18.
+
+## D27. Atmospheric density uses the height above the reference ellipsoid (step 8, GMAT comparison)
+- GMAT's exponential atmosphere uses the same Vallado table but the height above the reference ellipsoid. With a spherical
+  height urania differed from GMAT by 28.6 km after 3 days at 400 km and 51.64°: at the same |r| the ellipsoid height is up to
+  about 21 km larger at high latitude, so the density is 20 to 25% lower.
+- `Body.flattening` was added (Earth WGS 84 1/298.257223563, Moon 0.0012, Mars 0.00589), and `core.forces.geodetic_altitude`
+  computes the exact height (iterated geodetic latitude). `ExponentialAtmosphere(radius, flattening)` uses it.
+  With the same spin axis as GMAT the difference is now 3.3 m.
+- The surface-impact event and `Trajectory.altitude` stay spherical (|r| - R).
+
+## Note: the frame's z axis is taken as the spin axis
+- J2, atmospheric rotation and the ellipsoid all use the inertial z axis. GMAT uses the true pole of date, 7.69" from the J2000 z axis
+  at the J2000 epoch, which gives a 144 m difference after 7 days in the J2 scenario (3.3 m once both use the same axis).
+- Not changed in this step; recorded here because it matters for state vectors given in the J2000 frame at epochs far from J2000.