pyastropdl 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyastropdl-0.9.0/LICENSE +21 -0
- pyastropdl-0.9.0/PKG-INFO +216 -0
- pyastropdl-0.9.0/README.md +201 -0
- pyastropdl-0.9.0/pyastropdl/__init__.py +5 -0
- pyastropdl-0.9.0/pyastropdl/core/__init__.py +3 -0
- pyastropdl-0.9.0/pyastropdl/core/common/__init__.py +23 -0
- pyastropdl-0.9.0/pyastropdl/core/common/constants.py +10 -0
- pyastropdl-0.9.0/pyastropdl/core/common/interpolation.py +26 -0
- pyastropdl-0.9.0/pyastropdl/core/common/root_finding.py +47 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/__init__.py +0 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/__init__.py +27 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/engine.py +216 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/integrators.py +90 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/physics.py +55 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/residuals.py +73 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/dynamic_g/root_finding.py +62 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/__init__.py +26 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/engine.py +197 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/integrators.py +51 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/physics.py +48 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/residuals.py +72 -0
- pyastropdl-0.9.0/pyastropdl/core/simulation_engine/static_g/root_finding.py +55 -0
- pyastropdl-0.9.0/pyastropdl/core/solver.py +106 -0
- pyastropdl-0.9.0/pyastropdl/core/solvers/__init__.py +3 -0
- pyastropdl-0.9.0/pyastropdl/core/solvers/shooting_solver.py +79 -0
- pyastropdl-0.9.0/pyastropdl/core/utils/__init__.py +55 -0
- pyastropdl-0.9.0/pyastropdl/core/utils/paths.py +31 -0
- pyastropdl-0.9.0/pyastropdl/core/utils/tools.py +31 -0
- pyastropdl-0.9.0/pyastropdl/core/utils/types.py +41 -0
- pyastropdl-0.9.0/pyastropdl/visualization/__init__.py +4 -0
- pyastropdl-0.9.0/pyastropdl/visualization/animator.py +243 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/__init__.py +6 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/annotations.py +39 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/hud.py +193 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/plots.py +49 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/ticks.py +71 -0
- pyastropdl-0.9.0/pyastropdl/visualization/components/zoom.py +34 -0
- pyastropdl-0.9.0/pyastropdl/visualization/plotter.py +255 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/__init__.py +23 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/axes.py +104 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/colors.py +118 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/Geist/static/Geist-Bold.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/Geist/static/Geist-Medium.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/Geist/static/Geist-Regular.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/IBM_Plex_Mono/IBMPlexMono-Bold.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/IBM_Plex_Mono/IBMPlexMono-Medium.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/IBM_Plex_Mono/IBMPlexMono-Regular.ttf +0 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/__init__.py +3 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/fonts/fonts.py +141 -0
- pyastropdl-0.9.0/pyastropdl/visualization/style/themes.py +64 -0
- pyastropdl-0.9.0/pyastropdl.egg-info/PKG-INFO +216 -0
- pyastropdl-0.9.0/pyastropdl.egg-info/SOURCES.txt +55 -0
- pyastropdl-0.9.0/pyastropdl.egg-info/dependency_links.txt +1 -0
- pyastropdl-0.9.0/pyastropdl.egg-info/requires.txt +3 -0
- pyastropdl-0.9.0/pyastropdl.egg-info/top_level.txt +1 -0
- pyastropdl-0.9.0/pyproject.toml +32 -0
- pyastropdl-0.9.0/setup.cfg +4 -0
pyastropdl-0.9.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 angelet-dev
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pyastropdl
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: Powered Descent and Landing Solver (Lunar Edition)
|
|
5
|
+
Author: @angelet-dev
|
|
6
|
+
Project-URL: Homepage, https://github.com/angelet-dev/pyastropdl
|
|
7
|
+
Project-URL: Repository, https://github.com/angelet-dev/pyastropdl
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: numpy>=1.24.0
|
|
12
|
+
Requires-Dist: matplotlib>=3.5.0
|
|
13
|
+
Requires-Dist: numba>=0.57.0
|
|
14
|
+
Dynamic: license-file
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<img src=".github/assets/logo/logo.png" alt="PyAstroPDL Banner" width="80%">
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
# PyAstroPDL: Powered Descent and Landing Solver v0.9.0 (Lunar Edition)
|
|
21
|
+
|
|
22
|
+
**PyAstroPDL** is a high-performance Python package for solving 1D lunar soft-landing optimal control problems.
|
|
23
|
+
The package is designed with a modular architecture using JIT compilation (Numba) and contains an advanced toolkit for visualizing phase trajectories and telemetry.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
## 📐 Mathematical Core & Numerical Methods
|
|
27
|
+
|
|
28
|
+
The structure of the optimal control is derived via Pontryagin’s maximum principle.
|
|
29
|
+
|
|
30
|
+
The package’s mathematical core is based on three numerical methods:
|
|
31
|
+
|
|
32
|
+
1. **Shooting Method:** Used to reduce a complex BVP to a root-finding problem for a residual function by integrating an initial value problem at each iteration (shot) and adjusting a free parameter of the system (shooting parameter).
|
|
33
|
+
|
|
34
|
+
2. **Fourth-Order Runge-Kutta (RK4):** Used for numerical integration of the system of differential equations.
|
|
35
|
+
|
|
36
|
+
3. **Halley's Method:** Used to approximate roots with cubic convergence.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
## 🏗️ Architecture & Package Structure
|
|
40
|
+
|
|
41
|
+
The package is divided into two modules:
|
|
42
|
+
|
|
43
|
+
* **`pyastropdl.core`** — Computational module. It contains the implementation of the theoretical part of the algorithm for solving the 1D lunar soft-landing optimal control problem.
|
|
44
|
+
|
|
45
|
+
* **`Solver`** — A class for finding a solution based on the obtained system parameters and for calculating the residual functions.
|
|
46
|
+
|
|
47
|
+
* **`pyastropdl.visualization`** — Visualization module. It contains tools needed to graphically display the solution and the residual functions.
|
|
48
|
+
|
|
49
|
+
* **`Plotter`** — A class for displaying telemetry, phase trajectories, and residual plots.
|
|
50
|
+
|
|
51
|
+
* **`Animator`** — A class for generating an animation of the phase trajectory.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
## ⚙️ The Solver Class and Its Methods
|
|
55
|
+
|
|
56
|
+
* **`Solver(init_cond, end_cond, rocket_params, sim_engine)`** is a class for solving 1D lunar soft-landing problems. It takes boundary conditions, rocket parameters, and the simulation engine type as input: `init_cond` = $[m_0, v_0, h_0]$, `end_cond` = $[v(\tau), h(\tau)]$, `rocket_params` = $(u_{\max}, k, m_{\text{propellant}})$, `sim_engine` = `"static_g"` or `"dynamic_g"`.
|
|
57
|
+
|
|
58
|
+
* **`.solve(dt, eps)`** is a method for finding the solution to the BVP. It takes `dt` (simulation step) and `eps` (tolerance for root localization of the residual function). It returns an array of the spacecraft’s phase states corresponding to the found solution.
|
|
59
|
+
|
|
60
|
+
* **`.print_results()`** is a method for printing a concise report on the spacecraft’s state at optimal engine ignition ($t_s$) and at the terminal time $\tau$.
|
|
61
|
+
|
|
62
|
+
* **`.find_residuals(dt)`** is a method for calculating values of the residual functions. It takes `dt` (simulation step). It returns a tuple of two arrays: residual function values for terminal altitude and velocity, respectively.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
## ⚙️ The Simulation Engines
|
|
66
|
+
|
|
67
|
+
The Solver class supports switching between gravity models via the `sim_engine` parameter:
|
|
68
|
+
|
|
69
|
+
* **`static_g`** (Default) – Uses a static gravitational acceleration above the lunar surface $g = 1.6234 \text{ m/s}^2$.
|
|
70
|
+
|
|
71
|
+
* **`dynamic_g` [EXPERIMENTAL]** — Calculates gravitational acceleration dynamically depending on the spacecraft’s altitude.
|
|
72
|
+
|
|
73
|
+
> **⚠️ Warning:** The `dynamic_g` engine is currently in experimental mode. The calculation of $\Delta v$ is performed using a simplified formula for static gravitation. There may be unstable behavior of the algorithm for localizing the bounds $[t_{\min}, t_{\max}]$, which can lead to a failure to find a solution even if it exists.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
## ⚙️ The Plotter Class and Its Methods
|
|
77
|
+
|
|
78
|
+
* **`Plotter(solver)`** is a class for static visualization. It requires a Solver instance for initialization from which it automatically extracts the required data.
|
|
79
|
+
|
|
80
|
+
* **`.plot_trajectory(fname)`** is a method for displaying the spacecraft’s phase trajectory plot. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `phase_trajectory.png`.
|
|
81
|
+
|
|
82
|
+
* **`.plot_telemetry(fname)`** is a method for displaying the spacecraft’s time-series telemetry. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `telemetry.png`.
|
|
83
|
+
|
|
84
|
+
* **`.plot_residuals(fname)`** is a method for displaying the residual function plots. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `residuals.png`.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
## ⚙️ The Animator Class and Its Method
|
|
88
|
+
|
|
89
|
+
* **`Animator(solver)`** is a class for dynamic visualization. It requires a Solver instance for initialization from which it automatically extracts the required data.
|
|
90
|
+
|
|
91
|
+
* **`.animate(fps, duration, fname)`** is a method for generating an animation of the spacecraft’s phase trajectory. It takes `fps` (frame rate), `duration` (in seconds), `fname` (save path). It saves the video file relative to the current working directory. The default filename is `trajectory.mp4`.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 🚀 Quickstart
|
|
96
|
+
|
|
97
|
+
Install the package via pip:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pip install pyastropdl
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import pyastropdl as pdl
|
|
105
|
+
|
|
106
|
+
# === Condition of BVP ===
|
|
107
|
+
h_0 = 35000 # Initial altitude (m)
|
|
108
|
+
v_0 = 125 # Initial velocity (m/s)
|
|
109
|
+
m_0 = 750 # Initial mass of the spacecraft with the fuel (kg)
|
|
110
|
+
|
|
111
|
+
init_cond = [m_0, v_0, h_0]
|
|
112
|
+
|
|
113
|
+
h_tau = 0 # Condition on altitude for soft landing (m)
|
|
114
|
+
v_tau = 0 # Condition on velocity for soft landing (m/s)
|
|
115
|
+
|
|
116
|
+
end_cond = [v_tau, h_tau]
|
|
117
|
+
|
|
118
|
+
# === Rocket Parameters (DPS Engine) ===
|
|
119
|
+
u_max = 1700.0 # Max thrust (N)
|
|
120
|
+
isp = 311.0 # Specific impulse (s)
|
|
121
|
+
g_earth = 9.80665 # Standard Earth gravity constant (m/s^2)
|
|
122
|
+
|
|
123
|
+
# Mass flow rate coefficient k = 1 / (Isp * g_0)
|
|
124
|
+
k = 1.0 / (isp * g_earth)
|
|
125
|
+
|
|
126
|
+
m_propellant = 190 # Mass of propellant (kg)
|
|
127
|
+
|
|
128
|
+
rocket_params = (u_max, k, m_propellant)
|
|
129
|
+
|
|
130
|
+
# Initialisation of Solver
|
|
131
|
+
solver = pdl.Solver(init_cond, end_cond, rocket_params, sim_engine='static_g')
|
|
132
|
+
|
|
133
|
+
# Solve the system and print short results
|
|
134
|
+
solver.solve(dt=0.1)
|
|
135
|
+
solver.print_results()
|
|
136
|
+
|
|
137
|
+
# Find the residuals functions
|
|
138
|
+
solver.find_residuals(dt=0.1)
|
|
139
|
+
|
|
140
|
+
# Initialisation of Plotter
|
|
141
|
+
plotter = pdl.Plotter(solver)
|
|
142
|
+
|
|
143
|
+
# Plot the graphs of the spacecraft phase trajectory and telemetry
|
|
144
|
+
plotter.plot_trajectory()
|
|
145
|
+
plotter.plot_telemetry()
|
|
146
|
+
|
|
147
|
+
# Plot the residuals functions
|
|
148
|
+
plotter.plot_residuals()
|
|
149
|
+
|
|
150
|
+
# Initialisation of Animator
|
|
151
|
+
animator = pdl.Animator(solver)
|
|
152
|
+
|
|
153
|
+
# Animate the spacecraft trajectory
|
|
154
|
+
animator.animate(fps=60, duration=15)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
## 📊 Examples
|
|
159
|
+
Examples of the program output are available in the [Examples (static g).md](.github/Examples%20(static%20g).md) or [Examples (dynamic g).md](.github/Examples%20(dynamic%20g).md) file.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
## 📂 Repository Structure
|
|
163
|
+
```text
|
|
164
|
+
pyastropdl/
|
|
165
|
+
├── pyastropdl/ # Main Package Directory
|
|
166
|
+
│ ├── core/ # Computational module
|
|
167
|
+
│ │ ├── common/
|
|
168
|
+
│ │ ├── simulation_engine/ # Numerical integration & gravity models
|
|
169
|
+
│ │ ├── solvers/ # BVP shooting algorithm implementation
|
|
170
|
+
│ │ ├── utils/ # Helper functions, paths & type definitions
|
|
171
|
+
│ │ └── solver.py # Main Solver API entry point
|
|
172
|
+
│ │
|
|
173
|
+
│ └── visualization/ # Visualization module
|
|
174
|
+
│ ├── style/ # Visual presets (colors, fonts, themes)
|
|
175
|
+
│ ├── components/ # Components for vsisualization
|
|
176
|
+
│ ├── animator.py # Dynamic MP4 phase portrait rendering
|
|
177
|
+
│ └── plotter.py # Static telemetry charts generation
|
|
178
|
+
│
|
|
179
|
+
├── Paper/ # Theoretical derivation documents
|
|
180
|
+
├── pyproject.toml # Package build configuration
|
|
181
|
+
└── README.md
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## 🎓 Academic Background & Project Evolution
|
|
187
|
+
This project evolved from an initial short paper into an independent Python package and a full paper.
|
|
188
|
+
|
|
189
|
+
### 📜 Short Paper (ITEST-2026)
|
|
190
|
+
The initial mathematical problem formulation was published in the conference proceedings:
|
|
191
|
+
|
|
192
|
+
> **"DETERMINING THE SWITCHING AND LANDING TIME IN THE MOON SOFT LANDING PROBLEM" (p. 396.)**
|
|
193
|
+
> [*Conference proceedings of the VIII International Scientific-Practical Conference "Information Technology for Education, Science and Technics" (ITEST-2026)*](https://zenodo.org/records/21493752)
|
|
194
|
+
|
|
195
|
+
* **Theoretical development of the algorithm and code:** Tymoshchuk Dmytro (`@angelet_dev`)
|
|
196
|
+
* **Scientific supervision and organizational support:** Revina Tetiana
|
|
197
|
+
### 📑 The Full Paper and Python Package
|
|
198
|
+
This repository contains a paper (in the `Paper/` directory) accompanying the **PyAstroPDL** codebase.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
## 👤 Author
|
|
202
|
+
|
|
203
|
+
* **Tymoshchuk Dmytro** (`@angelet_dev`) — Sole developer of the **PyAstroPDL** package and author of the accompanying paper.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
## 🛠 Tech Stack
|
|
207
|
+
* **Core:** Python 3
|
|
208
|
+
* **Computation Engine:** NumPy, Numba (JIT).
|
|
209
|
+
* **Graphics:** Matplotlib.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
## 📜 License
|
|
213
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src=".github/assets/logo/logo.png" alt="PyAstroPDL Banner" width="80%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# PyAstroPDL: Powered Descent and Landing Solver v0.9.0 (Lunar Edition)
|
|
6
|
+
|
|
7
|
+
**PyAstroPDL** is a high-performance Python package for solving 1D lunar soft-landing optimal control problems.
|
|
8
|
+
The package is designed with a modular architecture using JIT compilation (Numba) and contains an advanced toolkit for visualizing phase trajectories and telemetry.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
## 📐 Mathematical Core & Numerical Methods
|
|
12
|
+
|
|
13
|
+
The structure of the optimal control is derived via Pontryagin’s maximum principle.
|
|
14
|
+
|
|
15
|
+
The package’s mathematical core is based on three numerical methods:
|
|
16
|
+
|
|
17
|
+
1. **Shooting Method:** Used to reduce a complex BVP to a root-finding problem for a residual function by integrating an initial value problem at each iteration (shot) and adjusting a free parameter of the system (shooting parameter).
|
|
18
|
+
|
|
19
|
+
2. **Fourth-Order Runge-Kutta (RK4):** Used for numerical integration of the system of differential equations.
|
|
20
|
+
|
|
21
|
+
3. **Halley's Method:** Used to approximate roots with cubic convergence.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
## 🏗️ Architecture & Package Structure
|
|
25
|
+
|
|
26
|
+
The package is divided into two modules:
|
|
27
|
+
|
|
28
|
+
* **`pyastropdl.core`** — Computational module. It contains the implementation of the theoretical part of the algorithm for solving the 1D lunar soft-landing optimal control problem.
|
|
29
|
+
|
|
30
|
+
* **`Solver`** — A class for finding a solution based on the obtained system parameters and for calculating the residual functions.
|
|
31
|
+
|
|
32
|
+
* **`pyastropdl.visualization`** — Visualization module. It contains tools needed to graphically display the solution and the residual functions.
|
|
33
|
+
|
|
34
|
+
* **`Plotter`** — A class for displaying telemetry, phase trajectories, and residual plots.
|
|
35
|
+
|
|
36
|
+
* **`Animator`** — A class for generating an animation of the phase trajectory.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
## ⚙️ The Solver Class and Its Methods
|
|
40
|
+
|
|
41
|
+
* **`Solver(init_cond, end_cond, rocket_params, sim_engine)`** is a class for solving 1D lunar soft-landing problems. It takes boundary conditions, rocket parameters, and the simulation engine type as input: `init_cond` = $[m_0, v_0, h_0]$, `end_cond` = $[v(\tau), h(\tau)]$, `rocket_params` = $(u_{\max}, k, m_{\text{propellant}})$, `sim_engine` = `"static_g"` or `"dynamic_g"`.
|
|
42
|
+
|
|
43
|
+
* **`.solve(dt, eps)`** is a method for finding the solution to the BVP. It takes `dt` (simulation step) and `eps` (tolerance for root localization of the residual function). It returns an array of the spacecraft’s phase states corresponding to the found solution.
|
|
44
|
+
|
|
45
|
+
* **`.print_results()`** is a method for printing a concise report on the spacecraft’s state at optimal engine ignition ($t_s$) and at the terminal time $\tau$.
|
|
46
|
+
|
|
47
|
+
* **`.find_residuals(dt)`** is a method for calculating values of the residual functions. It takes `dt` (simulation step). It returns a tuple of two arrays: residual function values for terminal altitude and velocity, respectively.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
## ⚙️ The Simulation Engines
|
|
51
|
+
|
|
52
|
+
The Solver class supports switching between gravity models via the `sim_engine` parameter:
|
|
53
|
+
|
|
54
|
+
* **`static_g`** (Default) – Uses a static gravitational acceleration above the lunar surface $g = 1.6234 \text{ m/s}^2$.
|
|
55
|
+
|
|
56
|
+
* **`dynamic_g` [EXPERIMENTAL]** — Calculates gravitational acceleration dynamically depending on the spacecraft’s altitude.
|
|
57
|
+
|
|
58
|
+
> **⚠️ Warning:** The `dynamic_g` engine is currently in experimental mode. The calculation of $\Delta v$ is performed using a simplified formula for static gravitation. There may be unstable behavior of the algorithm for localizing the bounds $[t_{\min}, t_{\max}]$, which can lead to a failure to find a solution even if it exists.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
## ⚙️ The Plotter Class and Its Methods
|
|
62
|
+
|
|
63
|
+
* **`Plotter(solver)`** is a class for static visualization. It requires a Solver instance for initialization from which it automatically extracts the required data.
|
|
64
|
+
|
|
65
|
+
* **`.plot_trajectory(fname)`** is a method for displaying the spacecraft’s phase trajectory plot. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `phase_trajectory.png`.
|
|
66
|
+
|
|
67
|
+
* **`.plot_telemetry(fname)`** is a method for displaying the spacecraft’s time-series telemetry. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `telemetry.png`.
|
|
68
|
+
|
|
69
|
+
* **`.plot_residuals(fname)`** is a method for displaying the residual function plots. It takes `fname` (save path). It saves the image relative to the current working directory. The default filename is `residuals.png`.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
## ⚙️ The Animator Class and Its Method
|
|
73
|
+
|
|
74
|
+
* **`Animator(solver)`** is a class for dynamic visualization. It requires a Solver instance for initialization from which it automatically extracts the required data.
|
|
75
|
+
|
|
76
|
+
* **`.animate(fps, duration, fname)`** is a method for generating an animation of the spacecraft’s phase trajectory. It takes `fps` (frame rate), `duration` (in seconds), `fname` (save path). It saves the video file relative to the current working directory. The default filename is `trajectory.mp4`.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🚀 Quickstart
|
|
81
|
+
|
|
82
|
+
Install the package via pip:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
pip install pyastropdl
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
import pyastropdl as pdl
|
|
90
|
+
|
|
91
|
+
# === Condition of BVP ===
|
|
92
|
+
h_0 = 35000 # Initial altitude (m)
|
|
93
|
+
v_0 = 125 # Initial velocity (m/s)
|
|
94
|
+
m_0 = 750 # Initial mass of the spacecraft with the fuel (kg)
|
|
95
|
+
|
|
96
|
+
init_cond = [m_0, v_0, h_0]
|
|
97
|
+
|
|
98
|
+
h_tau = 0 # Condition on altitude for soft landing (m)
|
|
99
|
+
v_tau = 0 # Condition on velocity for soft landing (m/s)
|
|
100
|
+
|
|
101
|
+
end_cond = [v_tau, h_tau]
|
|
102
|
+
|
|
103
|
+
# === Rocket Parameters (DPS Engine) ===
|
|
104
|
+
u_max = 1700.0 # Max thrust (N)
|
|
105
|
+
isp = 311.0 # Specific impulse (s)
|
|
106
|
+
g_earth = 9.80665 # Standard Earth gravity constant (m/s^2)
|
|
107
|
+
|
|
108
|
+
# Mass flow rate coefficient k = 1 / (Isp * g_0)
|
|
109
|
+
k = 1.0 / (isp * g_earth)
|
|
110
|
+
|
|
111
|
+
m_propellant = 190 # Mass of propellant (kg)
|
|
112
|
+
|
|
113
|
+
rocket_params = (u_max, k, m_propellant)
|
|
114
|
+
|
|
115
|
+
# Initialisation of Solver
|
|
116
|
+
solver = pdl.Solver(init_cond, end_cond, rocket_params, sim_engine='static_g')
|
|
117
|
+
|
|
118
|
+
# Solve the system and print short results
|
|
119
|
+
solver.solve(dt=0.1)
|
|
120
|
+
solver.print_results()
|
|
121
|
+
|
|
122
|
+
# Find the residuals functions
|
|
123
|
+
solver.find_residuals(dt=0.1)
|
|
124
|
+
|
|
125
|
+
# Initialisation of Plotter
|
|
126
|
+
plotter = pdl.Plotter(solver)
|
|
127
|
+
|
|
128
|
+
# Plot the graphs of the spacecraft phase trajectory and telemetry
|
|
129
|
+
plotter.plot_trajectory()
|
|
130
|
+
plotter.plot_telemetry()
|
|
131
|
+
|
|
132
|
+
# Plot the residuals functions
|
|
133
|
+
plotter.plot_residuals()
|
|
134
|
+
|
|
135
|
+
# Initialisation of Animator
|
|
136
|
+
animator = pdl.Animator(solver)
|
|
137
|
+
|
|
138
|
+
# Animate the spacecraft trajectory
|
|
139
|
+
animator.animate(fps=60, duration=15)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
## 📊 Examples
|
|
144
|
+
Examples of the program output are available in the [Examples (static g).md](.github/Examples%20(static%20g).md) or [Examples (dynamic g).md](.github/Examples%20(dynamic%20g).md) file.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
## 📂 Repository Structure
|
|
148
|
+
```text
|
|
149
|
+
pyastropdl/
|
|
150
|
+
├── pyastropdl/ # Main Package Directory
|
|
151
|
+
│ ├── core/ # Computational module
|
|
152
|
+
│ │ ├── common/
|
|
153
|
+
│ │ ├── simulation_engine/ # Numerical integration & gravity models
|
|
154
|
+
│ │ ├── solvers/ # BVP shooting algorithm implementation
|
|
155
|
+
│ │ ├── utils/ # Helper functions, paths & type definitions
|
|
156
|
+
│ │ └── solver.py # Main Solver API entry point
|
|
157
|
+
│ │
|
|
158
|
+
│ └── visualization/ # Visualization module
|
|
159
|
+
│ ├── style/ # Visual presets (colors, fonts, themes)
|
|
160
|
+
│ ├── components/ # Components for vsisualization
|
|
161
|
+
│ ├── animator.py # Dynamic MP4 phase portrait rendering
|
|
162
|
+
│ └── plotter.py # Static telemetry charts generation
|
|
163
|
+
│
|
|
164
|
+
├── Paper/ # Theoretical derivation documents
|
|
165
|
+
├── pyproject.toml # Package build configuration
|
|
166
|
+
└── README.md
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## 🎓 Academic Background & Project Evolution
|
|
172
|
+
This project evolved from an initial short paper into an independent Python package and a full paper.
|
|
173
|
+
|
|
174
|
+
### 📜 Short Paper (ITEST-2026)
|
|
175
|
+
The initial mathematical problem formulation was published in the conference proceedings:
|
|
176
|
+
|
|
177
|
+
> **"DETERMINING THE SWITCHING AND LANDING TIME IN THE MOON SOFT LANDING PROBLEM" (p. 396.)**
|
|
178
|
+
> [*Conference proceedings of the VIII International Scientific-Practical Conference "Information Technology for Education, Science and Technics" (ITEST-2026)*](https://zenodo.org/records/21493752)
|
|
179
|
+
|
|
180
|
+
* **Theoretical development of the algorithm and code:** Tymoshchuk Dmytro (`@angelet_dev`)
|
|
181
|
+
* **Scientific supervision and organizational support:** Revina Tetiana
|
|
182
|
+
### 📑 The Full Paper and Python Package
|
|
183
|
+
This repository contains a paper (in the `Paper/` directory) accompanying the **PyAstroPDL** codebase.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
## 👤 Author
|
|
187
|
+
|
|
188
|
+
* **Tymoshchuk Dmytro** (`@angelet_dev`) — Sole developer of the **PyAstroPDL** package and author of the accompanying paper.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
## 🛠 Tech Stack
|
|
192
|
+
* **Core:** Python 3
|
|
193
|
+
* **Computation Engine:** NumPy, Numba (JIT).
|
|
194
|
+
* **Graphics:** Matplotlib.
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
## 📜 License
|
|
198
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
from .constants import (
|
|
2
|
+
G_EARTH,
|
|
3
|
+
G_MOON,
|
|
4
|
+
GM_MOON,
|
|
5
|
+
MAX_ITERATIONS_STEPS,
|
|
6
|
+
MAX_RESIDUALS_STEPS,
|
|
7
|
+
MAX_SIMULATION_STEPS,
|
|
8
|
+
R_MOON,
|
|
9
|
+
)
|
|
10
|
+
from .interpolation import lerp_inplace
|
|
11
|
+
from .root_finding import halley_method
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"GM_MOON",
|
|
15
|
+
"G_EARTH",
|
|
16
|
+
"G_MOON",
|
|
17
|
+
"MAX_ITERATIONS_STEPS",
|
|
18
|
+
"MAX_RESIDUALS_STEPS",
|
|
19
|
+
"MAX_SIMULATION_STEPS",
|
|
20
|
+
"R_MOON",
|
|
21
|
+
"halley_method",
|
|
22
|
+
"lerp_inplace"
|
|
23
|
+
]
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
from numba import njit
|
|
2
|
+
|
|
3
|
+
from pyastropdl.core.utils.types import StateVector, f64_1d, i64, void
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
@njit(void(f64_1d, f64_1d, f64_1d, i64), cache=True, fastmath=True)
|
|
7
|
+
def lerp_inplace(
|
|
8
|
+
curr_state: StateVector,
|
|
9
|
+
prev_state: StateVector,
|
|
10
|
+
end_state: StateVector,
|
|
11
|
+
mode: int
|
|
12
|
+
) -> None:
|
|
13
|
+
|
|
14
|
+
# mode: 0 - velocity, 1 - altitude
|
|
15
|
+
theta = 0.0
|
|
16
|
+
|
|
17
|
+
match mode:
|
|
18
|
+
case 0:
|
|
19
|
+
dv = curr_state[1] - prev_state[1]
|
|
20
|
+
theta = (end_state[0] - prev_state[1]) / dv if abs(dv) > 1e-9 else 0.0
|
|
21
|
+
case 1:
|
|
22
|
+
dh = curr_state[2] - prev_state[2]
|
|
23
|
+
theta = (end_state[1] - prev_state[2]) / dh if abs(dh) > 1e-9 else 0.0
|
|
24
|
+
|
|
25
|
+
for i in range(4):
|
|
26
|
+
curr_state[i] = prev_state[i] + theta * (curr_state[i] - prev_state[i])
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import numpy as np
|
|
2
|
+
from numpy import nan
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
def halley_method(
|
|
6
|
+
func,
|
|
7
|
+
func_args: tuple,
|
|
8
|
+
t_bounds: tuple,
|
|
9
|
+
eps: float = 1e-5,
|
|
10
|
+
max_iter: int = 100,
|
|
11
|
+
) -> float:
|
|
12
|
+
|
|
13
|
+
t_min, t_max = t_bounds
|
|
14
|
+
ti = t_max
|
|
15
|
+
|
|
16
|
+
for _ in range(max_iter):
|
|
17
|
+
|
|
18
|
+
f_val = func(ti, func_args)
|
|
19
|
+
if abs(f_val) <= eps:
|
|
20
|
+
return ti
|
|
21
|
+
|
|
22
|
+
f_left = func(ti - eps, func_args)
|
|
23
|
+
f_right = func(ti + eps, func_args)
|
|
24
|
+
|
|
25
|
+
f_dx = (f_right - f_left) / (2.0 * eps)
|
|
26
|
+
f_ddx = (f_right - 2.0 * f_val + f_left) / (eps**2)
|
|
27
|
+
|
|
28
|
+
denominator = 2.0 * (f_dx**2) - f_val * f_ddx
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
if abs(denominator) < 1e-12:
|
|
32
|
+
return nan
|
|
33
|
+
|
|
34
|
+
ti += -(2.0 * f_val * f_dx) / denominator
|
|
35
|
+
|
|
36
|
+
if np.isnan(ti):
|
|
37
|
+
return nan
|
|
38
|
+
|
|
39
|
+
if ti >= t_max:
|
|
40
|
+
ti = t_max - eps
|
|
41
|
+
t_max -= 0.1
|
|
42
|
+
elif ti <= t_min:
|
|
43
|
+
ti = t_min + eps
|
|
44
|
+
t_min += 0.1
|
|
45
|
+
|
|
46
|
+
return nan
|
|
47
|
+
|
|
File without changes
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
from .engine import (
|
|
2
|
+
get_ff_phase,
|
|
3
|
+
get_start_cond,
|
|
4
|
+
get_terminal_state,
|
|
5
|
+
get_time_boundary,
|
|
6
|
+
get_trajectory,
|
|
7
|
+
)
|
|
8
|
+
from .integrators import rk4_bp_inplace, rk4_ffp_inplace
|
|
9
|
+
from .physics import braking_ode, free_fall_ode, get_g
|
|
10
|
+
from .residuals import altitude_residual, residual_func
|
|
11
|
+
from .root_finding import halley_method
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"altitude_residual",
|
|
15
|
+
"braking_ode",
|
|
16
|
+
"free_fall_ode",
|
|
17
|
+
"get_ff_phase",
|
|
18
|
+
"get_g",
|
|
19
|
+
"get_start_cond",
|
|
20
|
+
"get_terminal_state",
|
|
21
|
+
"get_time_boundary",
|
|
22
|
+
"get_trajectory",
|
|
23
|
+
"halley_method",
|
|
24
|
+
"residual_func",
|
|
25
|
+
"rk4_bp_inplace",
|
|
26
|
+
"rk4_ffp_inplace"
|
|
27
|
+
]
|