Add detailed comments for python example files (#1308)#1314
Add detailed comments for python example files (#1308)#1314seanmcleod70 merged 3 commits intoJSBSim-Team:masterfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1314 +/- ##
=======================================
Coverage 24.81% 24.81%
=======================================
Files 169 169
Lines 19631 19631
=======================================
Hits 4872 4872
Misses 14759 14759 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
examples/python/Rudder Kick.ipynb
Outdated
| "# Attempt to trim the aircraft.\n", | ||
| "try:\n", | ||
| " fdm['simulation/do_simple_trim'] = 1\n", | ||
| " # 1 means zero accelerations and constant attitude, usually for straight-and-level flight\n", |
There was a problem hiding this comment.
Mostly correct, but 'constant attitude' isn't a requirement. The angular accelerations, p-dot, q-dot, r-dot need to be 0, but the angular velocities, p, q, r don't need to be 0. So you can trim with a specific roll rate, e.g. p=5deg/s.
See for more details, 1 == tFull:
jsbsim/src/initialization/FGTrim.h
Lines 67 to 92 in 30a7261
And
jsbsim/src/initialization/FGInitialCondition.h
Lines 215 to 217 in 30a7261
There was a problem hiding this comment.
Thank you for the comment. I misunderstand the trim.
I understand that trim itself means stay with initial conditions, and trim mode means which acceleration component should be zero. Is this correct?
The comment should be # 1 means zero recti-linear and angular accelerations, usually for straight-and-level flight?
(while level have to be set by initial conditions.)
I am confused.
Someday, I would like to create examples of changeable property lists, trim mode lists, optimal usage situations, and so on.
There was a problem hiding this comment.
I think there is often a common misconception that trim implies that the angular velocities need to all be 0. Just like the translational velocities don't need to be 0, if they did have to be 0 then the only trim solutions would be stationary trim solutions on the ground, there is no requirement for the angular velocities to be 0, they can be 0, but they don't have to be, the only constraint for both the translational velocities and angular velocities is that they be constant, i.e. that their accelerations are 0.
Hence my comment that your original comment claiming that trim requires a constant attitude isn't accurate.
Take a look at the following paper for some more details on trim.
A General Solution to the Aircraft Trim Problem
Note that there are multiple ways to solve the trim problem, the one described in the paper I linked to is not currently available in JSBSim. The current trim algorithm in JSBSim is based on a different algorithm.
There was a problem hiding this comment.
Thank you very much. I read this paper, and found it very easy to understand. I realized that trim is actually very profound.
I understand that trim refers to determining a constant control values that brings the aircraft to a steady state where linear/angular accelerations are zero and linear/angular velocities are constant. And this condition is satisfied not only when flying straight, but also when performing steady turns or pull-up.
Also, I understand that level flight was achieved if the user set fdm['ic/h-sl-ft'].
The comment should be # 1 means straight flight by using all changeable control variables. right?
There was a problem hiding this comment.
You can thank @agodemar regarding the paper since he's one of the authors and also a JSBSim developer 😉
Also, I understand that level flight was achieved if the user set fdm['ic/h-sl-ft'].
No, what will indicate that you want level flight is setting gamma
fdm['ic/gamma-deg'] = gamma
You need to set fdm[ic/h-sl-ft'] to some value even if you're requesting a trim that involves climbing or descending flight. So setting it doesn't request level (non changing altitude) trim. Gamma controls that, pretty sure it defaults to 0 if you don't explicitly set it.
1 - tFull - Longitudinal and lateral trim.
There was a problem hiding this comment.
@yuki-2000 yes, trimming a dynamical system is a subtle subject, especially when the system is a flying vehicle in atmosphere.
One example of subtlelty is this:
When you trim for a flight along a rectilinear trajectory with a nonzero flight path angle (
So, rigourously, to keep a steady airspeed magnitude (and steady angle of attack
A similar reasoning is valid for a pull-up condition.
There was a problem hiding this comment.
You run into this issue of the trim only being valid in the near term even for level trim cases, i.e.
Now 'near term' is larger for this case than the climbing/descending case.
JSBSim offers a property to prevent the fuel burn affecting the mass and moments of inertia.
propulsion/fuel_freeze
There was a problem hiding this comment.
I understand that trim the plane just once doesn't mean it will stay the state forever. Thank you for your lecture.
So, does real commercial air plane trim itself at regular intervals repeatedly ?
There was a problem hiding this comment.
In effect yes, either the pilot if they are hand-flying or the autopilot when it's engaged, which for commercial airliners is for a large percentage of the overall flight.
So for example the autopilot would be configured to maintain some altitude, e.g. 33,000ft at some speed, e.g. Mach 0.82 and it will then continuously modify the control surfaces and the engine throttles to maintain that.
Out of interest, what is your background and what are you using JSBSim for?
There was a problem hiding this comment.
Out of interest, what is your background and what are you using JSBSim for?
Well, I studied aerospace engineering in the university, so I could somehow keep up with your discussions. However, my research field in the university was structure. I wanted to learn the flight dynamics and control for a step up or make flight simulator using UE5 as a part of my hobby (I do not know whether I can do it by the way)
I just find JSBSim just a few month ago from UE5`s antoinette project website, and tried to build in my environment and find it very hard. Therefore, I learn JSBSim little by little.
I might dissapear if I lose interest in the simulator or my job gets busy, but I try to continue studying.
| "\n", | ||
| "def thrust_vector_range_test(altitude, speed, flight_path_angle, title):\n", | ||
| " # altitude: altitude above sea level (ft)\n", | ||
| " # speed: mach number of speed (<1)\n", |
There was a problem hiding this comment.
Detail that speed can be Mach number if it's < 1 as you have, but also mention that > 1 specific KCAS (Knots Calibrated Air Speed).
| " # Track minimum thrust\n", | ||
| " min_thrust = 1000000\n", | ||
| " min_angle = 100\n", | ||
| " # Initialize the minimum thrust and thrust vectoring angles to a very large number.\n", |
There was a problem hiding this comment.
Mention it's to track/record the minimum thrust and the angle at which the minimum occurs.
| " thrust = fdm[\"propulsion/engine[0]/thrust-lbs\"]*2 # because there are two engines\n", | ||
| " thrusts.append(thrust)\n", | ||
| "\n", | ||
| " # update the minimum thrust and thrust vectoring angles.\n", |
There was a problem hiding this comment.
Start sentence with capital letter, i.e. # Update the....
examples/python/Trim Envelope.ipynb
Outdated
| "altitude = 15000\n", | ||
| "min_gamma = -10\n", | ||
| "max_gamma = 10\n", | ||
| "min_speed = 120 # Set the minimum airspeed (kts).\n", |
There was a problem hiding this comment.
Mention for the min and max speeds that it's CAS
examples/python/Trim Envelope.ipynb
Outdated
| " # Trim\n", | ||
| " # Trim the aircraft.\n", | ||
| " try:\n", | ||
| " # 1 means zero accelerations and constant attitude, usually for straight-and-level flight\n", |
There was a problem hiding this comment.
See earlier comment about comment about 1 - tFull trim comment.
|
Thanks @yuki-2000, overall looks good, have added a couple of minor comments. |
|
I fix the comments based of above discussions. |
|
Oh, what happened to the test? |
|
Yep, don't worry about that 1 particular failure. As you said you only modified .ipynb files, but by default any commit kicks off the full CI in terms of rebuilding everything and testing it etc. If you know for sure your commits don't modify any files that require a build to be kicked off, e.g. editing documentation like the README or these .ipynb files then you can add a [skip ci] label to the commit description to prevent the rebuild etc. |
|
Thanks @yuki-2000, I've just merged your PR in. |
|
Thank you very much. |
|
One of my main jobs as a flight instruction is to keep repeating “pitch, power, trim” over and over and over again. ;-)
Followed by “aviate, navigate, communicate”.
…--Adam
On Aug 4, 2025, at 8:15 AM, yuki-2000 ***@***.***> wrote:
@yuki-2000 commented on this pull request.
In examples/python/Rudder Kick.ipynb <#1314 (comment)>:
> "try:\n",
- " fdm['simulation/do_simple_trim'] = 1\n",
+ " # 1 means zero accelerations and constant attitude, usually for straight-and-level flight\n",
I understand that trim the plane just once doesn't mean it will stay the state forever. Thank you for your lecture.
So, does real commercial air plane trim itself at regular intervals repeatedly ?
—
Reply to this email directly, view it on GitHub <#1314 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABQ44XEQT337ZORWPVZ56ED3L5FH5AVCNFSM6AAAAACC7LDD2WVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTAOBTHEYTCMZTGY>.
You are receiving this because you are subscribed to this thread.
|
This kind of inconvenience should be avoided by prepending the PR title with Also speaking about good practices, I am not fond of inserting the discussion/issue number in the PR title:
Just some food for thoughts. |
Well, this is redundant information from myself 😄 I've read your message too fast @seanmcleod70 |
No problem, I've done that myself a couple of times with some of your comments 😉 |
Hello.
I added comments for beginners to the example files in examples/python, except for AoA vs CAS.ipynb because @agodemar just has improved it.
As a beginner of JSBSim, I added comments about what each variable I didn't understand meant, what the unit system was, jsbsim's unique settings, and the general flow of the whole process.
This time, I used the original comments as much as possible and did not change the code itself at all.
I apologize if @agodemar has already working on these 3 files.
Also, I found a few bugs in the code, so I will post them to issues later.