Is there need for python example file update with detailed comment ?

[yuki-2000]

Hello.

I just find this great project and try to understand and use this simulator.
I use python and think that example programs in example/python are lack of explanation comment thought program itself is good.
For example, for beginners (me), it is difficult to understand overall flow or what the variable refers to for the first time.

The code below is the original program of Rudder Kick.ipynb with detailed explanatory comments added using ChatGPT.

Is there any demand for a merge request for a program with additional explanatory comments like this?
I hope more and more people find and use this project.

Thank you.

import jsbsim
import matplotlib.pyplot as plt
import math

# --- Configuration Section ---
# Global variables that must be modified to match your particular need
# The aircraft name
# Note - It should match the exact spelling of the model file
AIRCRAFT_NAME="737"
# Path to JSBSim files, location of the folders "aircraft", "engines" and "systems"
PATH_TO_JSBSIM_FILES="../.."


# --- JSBSim Initialization ---
# These lines initialize the flight dynamics model.

# Avoid flooding the console with log messages
jsbsim.FGJSBBase().debug_lvl = 0

# Create a flight dynamics model (FDM) instance.
fdm = jsbsim.FGFDMExec(PATH_TO_JSBSIM_FILES)

# Load the aircraft model
fdm.load_model(AIRCRAFT_NAME)


# --- Simulation Parameters ---
# These lines set the simulation parameters.

# Set engines running
fdm['propulsion/set-running'] = -1

# Set alpha range for trim solutions
fdm['aero/alpha-max-rad'] = math.radians(12)   # Maximum angle of attack in radians.
fdm['aero/alpha-min-rad'] = math.radians(-4.0) # Minimum angle of attack in radians.

# Get the simulation time step (delta time).
dt = fdm.get_delta_t()

# Max control deflection
aileronMax = 1    # Maximum normarized aileron command (-1~1)
rudderMax = 0.92  # Maximum normarized rudder command (-1~1)

# Number of seconds for control surface to reach max deflection
risetime = 3

# Calculate the increment (change) in control surface deflection command per time step.
diAileron = aileronMax / (risetime/dt)
diRudder = rudderMax / (risetime/dt)


# --- Data Storage ---
# This section initializes lists to record simulation data.

times = []      # List to record the simulation time at each step.
betas = []      # List to record the beta angle at each step.
bankAngle = []  # List to record the bank angle at each step.
ailerons = []   # List to record the aileron control surface deflection.
rudder = []     # List to record the rudder control surface deflection.


# --- Initial Conditions ---
# These lines set the initial state of the aircraft.

fdm['ic/h-sl-ft'] = 1000  # Initial altitude in feet.
fdm['ic/vc-kts'] = 200    # Initial airspeed in knots.
fdm['ic/gamma-deg'] = 0   # Initial descent angle in degrees.
fdm['ic/beta-deg'] = 0    # Initial beta angle in degrees.


# --- Simulation Initialization ---
# This line initializes the flight dynamics model.

# Initialize the aircraft with initial conditions
fdm.run_ic() 

# Trim
try:
    fdm['simulation/do_simple_trim'] = 1  # Attempt to trim the aircraft.
except jsbsim.TrimFailureError:
    print("Trim failed, continuing rudder kick in an untrimmed state.")
    pass  # Ignore trim failure


# --- Simulation Loop ---
# This is the main simulation loop that runs the simulation for a specified duration.

# The total simulation time in seconds.
run_period = 20

for i in range(int(run_period/dt)):
    # Advance the simulation by one time step.
    fdm.run()

    # Record the simulation data.
    times.append(fdm.get_sim_time())
    betas.append(fdm['aero/beta-deg'])
    bankAngle.append(fdm['attitude/phi-deg'])
    ailerons.append(fdm['fcs/aileron-cmd-norm'])
    rudder.append(fdm['fcs/rudder-cmd-norm'])

    # Control Surface Update
    aileronCmd = fdm['fcs/aileron-cmd-norm']
    rudderCmd = fdm['fcs/rudder-cmd-norm']

    # Increment the aileron command if it's less than the maximum.
    if aileronCmd < aileronMax:
        aileronCmd += diAileron
        fdm['fcs/aileron-cmd-norm'] = aileronCmd

    # Increment the rudder command if it's less than the maximum.
    if rudderCmd < rudderMax:
        rudderCmd += diRudder
        fdm['fcs/rudder-cmd-norm'] = rudderCmd


# --- Plot Results ---
# This section plots the simulation results.

plt.rcParams["figure.figsize"] = (12, 8)  # Set the figure size.
fig, ax1 = plt.subplots()

# Plot the beta data on the primary y-axis.
ax1.set_xlabel('Time (s)')
ax1.set_ylabel('Beta (deg)')
line1 = ax1.plot(times, betas, label='Beta', color='red')

# Create a secondary y-axis for the control surface positions.
ax2 = ax1.twinx()
# Plot the aileron and rudder commands on the secondary y-axis.
ax2.set_ylabel('Inceptor Position')
line2 = ax2.plot(times, ailerons, label='Aileron')
line3 = ax2.plot(times, rudder, label='Rudder')

# Add a legend to the plot.
ax1.legend(handles=line1+line2+line3, loc=4) # Display the legend in the upper-right corner.
# Set the title of the plot.
plt.title('Rudder Kick')

# Display the plot.
plt.show()

[yuki-2000]

Is there any comments?

[seanmcleod70]

@yuki-2000 sorry, got distracted by your Google Colab PR.

Yes additional comments would be useful.

with detailed explanatory comments added using ChatGPT

No problem, just double-check carefully what ChatGPT produces.

[yuki-2000]

Thank you for your comment.
So, I will try to add comments to the other example files and try to make pull request.

No problem, just double-check carefully what ChatGPT produces.
Of course, I check it multiply.

[yuki-2000]

comments are added in #1314