🚀 GEO Optimization & Orbital Dynamics

A dual language library for GEO spacecraft propulsion optimisation and orbital mechanics. The same physics; Hohmann transfers, J2 secular perturbations, electric thruster trade space optimisation, is implemented in both Python and MATLAB so that results can be cross verified at every step of the mission design cycle.

---

📋 Overview

This library bridges the gap between rapid research workflows (Python) and flight-software simulation environments (MATLAB/Simulink). Every physical equation is implemented identically in both languages, test-verified against published reference values, and documented with LaTeX mathematics.

---

✨ Why Dual Language?

Aerospace engineering workflows typically span two toolchains:

Phase	Preferred Environment
🔬 Rapid research & algorithm development	Python (NumPy, SciPy, Astropy)
🛰️ Flight-software simulation & heritage tools	MATLAB / Simulink
✅ Verification & cross-check	Both

Maintaining a single source of truth across both languages means:

• 🔁 Results produced in Python can be independently validated in MATLAB before they appear in a flight-software simulation
• 📐 MATLAB Simulink models can import the same thruster parameters that were optimised in Python
• 🤝 Engineers can work in whichever language they know without losing access to the validated physics kernel

---

🗂️ Repository Layout

geo_optimization/
│
├── 🐍 python/                          Python package
│   ├── pyproject.toml                  PEP 517/518 build configuration
│   └── src/geo_opt/
│       ├── __init__.py                Package root (version, metadata)
│       ├── constants.py                Physical & orbital constants (astropy.units)
│       ├── dynamics/
│       │   ├── __init__.py            Convenience re-exports for short imports
│       │   ├── keplerian.py            Vis-viva, circular velocity, Hohmann transfer
│       │   └── perturbations.py        J2 RAAN & ω drift, station-keeping budget
│       ├── propulsion/
│       │   ├── __init__.py            Convenience re-exports for short imports
│       │   ├── thruster.py             Generic rocket eqn + Pydantic config
│       │   ├── het.py                  Hall-Effect Thruster model
│       │   └── ion.py                  Gridded Ion Thruster model
│       └── optimization/
│           └── solvers.py              Grid-search & SciPy L-BFGS-B solvers
│
├── 🔶 matlab/                          MATLAB package (+geo_opt namespace)
│   ├── startup.m                       Adds library paths — run once per session
│   ├── +geo_opt/
│   │   ├── constants.m                 Returns authoritative constant struct
│   │   ├── +dynamics/
│   │   │   ├── circular_velocity.m
│   │   │   ├── vis_viva.m
│   │   │   ├── hohmann_transfer.m
│   │   │   ├── orbital_period.m
│   │   │   ├── j2_raan_drift.m
│   │   │   └── j2_argperigee_drift.m
│   │   ├── +propulsion/
│   │   │   ├── calculate_thrust.m
│   │   │   ├── estimate_power.m
│   │   │   ├── thrust_to_power_ratio.m
│   │   │   ├── tsiolkovsky_dv.m
│   │   │   ├── het_performance.m
│   │   │   └── ion_performance.m
│   │   └── +optimization/
│   │       ├── grid_search.m           Exhaustive mesh optimiser
│   │       └── fmincon_optimizer.m     fmincon continuous solver
│   └── tests/
│       ├── test_dynamics.m
│       ├── test_propulsion.m
│       └── test_optimization.m
│
├── 📄 .gitignore
├── 📄 LICENSE
└── 📄 README.md

---

🚀 Quick Start — Python

# Install from the python/ subdirectory
pip install -e "python/[dev]"

# Run all tests
cd python && pytest

from astropy import units as u
from geo_opt.constants import R_LEO, R_GEO

# ✨ Convenience imports — short form (recommended)
from geo_opt.dynamics import hohmann_transfer
from geo_opt.propulsion import ThrusterConfig, HETModel

# 📦 Fully qualified imports also work
# from geo_opt.dynamics.keplerian import hohmann_transfer
# from geo_opt.propulsion.thruster import ThrusterConfig
# from geo_opt.propulsion.het import HETModel

from geo_opt.optimization.solvers import grid_search_optimizer

# --- 🛸 Hohmann Transfer: LEO → GEO ---
result = hohmann_transfer(R_LEO, R_GEO)
print(f"Total ΔV = {result['dv_total'].to('km/s'):.4f}")
# Total ΔV = 3.8933 km / s

# --- ⚡ HET Performance ---
cfg = ThrusterConfig(name="SPT-100", isp_s=1600, efficiency=0.50,
                     mass_flow_kg_s=5e-6)
het = HETModel(cfg)
perf = het.performance()
print(f"Thrust = {perf['thrust_mN']:.3f} | Power = {perf['input_power_W']:.1f}")

# --- 🎯 Thruster Optimisation ---
opt = grid_search_optimizer(isp_range=(1000, 4000), efficiency=0.55)
print(f"Optimal F/P = {opt.thrust_to_power.to('mN/W'):.4f}")

---

🔶 Quick Start — MATLAB

% From the MATLAB command window, run startup once:
run('matlab/startup.m')

% 🛸 Hohmann Transfer: LEO → GEO
C      = geo_opt.constants();
result = geo_opt.dynamics.hohmann_transfer(C.R_LEO, C.R_GEO);
fprintf('Total dV = %.4f km/s\n', result.dv_total/1e3);
% Total dV = 3.8933 km/s

% ⚡ HET Performance
perf = geo_opt.propulsion.het_performance(1600, 5e-6, 0.50);
fprintf('Thrust = %.3f mN | Power = %.1f W\n', perf.thrust_mN, perf.power_W);

% 🎯 Thruster Optimisation
opt = geo_opt.optimization.grid_search([1000 4000], [5e-5 1e-3], 0.55);
fprintf('Optimal F/P = %.4f mN/W\n', opt.thrust_to_power * 1e3);

% ✅ Run tests
results = runtests('tests/test_dynamics');
disp(table(results))

---

🔧 Physical Models

🌍 Orbital Dynamics

Model	Equation
Circular velocity	$v_c = \sqrt{\mu/r}$
Vis-viva	$v = \sqrt{\mu(2/r - 1/a)}$
Hohmann ΔV₁	$\Delta v_1 = \sqrt{\mu/r_1}\left(\sqrt{2r_2/(r_1+r_2)}-1\right)$
Hohmann ΔV₂	$\Delta v_2 = \sqrt{\mu/r_2}\left(1-\sqrt{2r_1/(r_1+r_2)}\right)$
J2 RAAN drift	$\dot{\Omega} = -\tfrac{3}{2}n J_2(R_\oplus/p)^2\cos i$
J2 ω drift	$\dot{\omega} = \tfrac{3}{4}n J_2(R_\oplus/p)^2(5\cos^2 i - 1)$

⚡ Propulsion

Model	Equation
Thrust	$F = \dot{m},I_{sp},g_0$
Input power	$P_{in} = \tfrac{1}{2}\dot{m}v_e^2/\eta$
Thrust-to-power	$F/P = 2\eta/(I_{sp},g_0)$
Rocket equation	$\Delta v = I_{sp},g_0,\ln(m_0/m_f)$

🛰️ Thruster Performance Envelopes

Type	$I_{sp}$ range (s)	Efficiency	Application
⚡ Hall-Effect (HET)	1 200 – 3 500	45 – 65 %	GEO station-keeping, orbit raising
🔬 Gridded Ion	2 500 – 10 000	55 – 80 %	Deep-space, high-ΔV GEO

---

📊 Physical Constants

Symbol	Value	Unit	Source
$g_0$	9.80665	m s⁻²	ISO 80000-3
$\mu_\oplus$	3.986 004 418 × 10¹⁴	m³ s⁻²	WGS-84
$R_\oplus$	6 378 137	m	WGS-84
$J_2$	1.082 626 68 × 10⁻³	—	IERS 2010
$r_{GEO}$	42 164 137	m	derived

---

✅ Running the Tests

🐍 Python

cd python
pip install -e ".[dev]"
pytest -v

🔶 MATLAB

run('matlab/startup.m')
runtests('matlab/tests/test_dynamics')
runtests('matlab/tests/test_propulsion')
runtests('matlab/tests/test_optimization')

---

🛠️ Technical Specifications

⚙️ Optimization Parameters

• ✅ Specific Impulse Range: 1 000 – 10 000 seconds
• ✅ Mass Flow Rate Range: 0.00005 – 0.001 kg/s
• ✅ Customisable efficiency parameters
• ✅ Real-time thrust and power calculations
• ✅ Multi-objective optimisation support
• ✅ Gravity-assist multiplier support

🔬 Validation

• ✅ All reference values anchored to Vallado (2013) & Curtis (2020)
• ✅ Python tests use astropy.units for unit-safe comparisons
• ✅ MATLAB tests use functiontests with RelTol/AbsTol tolerances
• ✅ Cross-language parity verified: LEO→GEO ΔV = 3.893 km/s in both
• ✅ Pydantic ThrusterConfig enforces physical bounds (Isp, efficiency, mass flow)
• ✅ Consistent input guards across all propulsion functions (positive Isp, positive mass flow, 0 < η ≤ 1)

---

📖 Citation

@misc{ATaylor_GEOOptimization_2026,
  author  = {A. Taylor},
  title   = {GEO Optimization \& Orbital Dynamics — Dual-Language Library},
  year    = {2026},
  url     = {https://github.com/ATaylorAerospace/geo_optimization}
}

---

📬 Contact

Have questions, ideas, or want to collaborate? Reach out to A Taylor directly: