Add pitch SAS implementation with Jupyter notebook

[ANF1S]

This PR adds a Jupyter notebook example demonstrating a pitch Stability Augmentation System (SAS) implementation for the A-4 Skyhawk aircraft using JSBSim python module.

The work was originated from the Show and Tell discussion: #1448 , where it was suggested submitting a PR after completing the Jupiter notebook example.

Changes:

• Added a new aircraft/A4x aircraft based on the original aircraft/A4 to implement the pitch SAS example from the baseline aircraft model.
• Added a new pitch_sas.xml system file, where the pitch SAS logic is located.
• Integrated the pich SAS output in the pitch <channel> of the modified aircraft configuration.
• Added a first order lag <actuator> model in the pitch <channel> to introduce response delay between control command and elevator deflection.
• Added an A-4 image in examples/python/images
• Added a Jupter notebook examples/python/test_pitch_sas.ipynb demonstrating:
  • The use of pitch SAS design.
  • Elevator doublet test.
  • Aircraft responses visualization.
  • Analytical verification showing changes in damping ratio and natural frequency.

The goal is to provide educational example showing how a SAS can be implemented through xml system file and exercised from python.

Notes:

• In the first cell of the notebook, PATH_TO_JSBSIM_FILES= has "--/--" value due to the relative path to the directory where the FDM is located.

[agodemar]

@ANF1S thank you for submitting this well written example!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 25.15%. Comparing base (e5446e1) to head (e438fd6).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1464   +/-   ##
=======================================
  Coverage   25.15%   25.15%           
=======================================
  Files         169      169           
  Lines       18811    18811           
=======================================
  Hits         4731     4731           
  Misses      14080    14080           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[seanmcleod70]

@ANF1S thanks for the Jupyter notebook writeup, it looks good. Will still take a closer look, but one initial thing that we need to think about is the location of the aircraft model.

I don't think it's a good idea and scalable to add a slightly modified version of an existing aircraft in the repo for potentially each example notebook that needs a modified FDM.

I think it would be better to have an aircraft sub-directory within examples\python, e.g. examples\python\aircraft\A4SAS.

May require a bit of extra work to get it to work with Google Colab.

[agodemar]

@seanmcleod70

I think it would be better to have an aircraft sub-directory within examples\python, e.g. examples\python\aircraft\A4SAS.

I agree on this: having a local aircraft folder in examples will not pollute the official collection of FDMs.

@ANF1S could you please relocate your input files

• A4x.xml renamed A4SAS.xml
• pitch_sas.xml

in examples/python/aircraft/A4SAS?

A note on the notebook test_pitch_sas.ipynb: in the bottom plot of the stacked plots produced by cell [6], please add a legend saying that the orange curve is the elevator command.

[ANF1S]

@agodemar , @seanmcleod70 Thanks so much for your feedback. I will make those changes.

[agodemar]

@ANF1S thanks for providing corrected files.
@seanmcleod70 for me the changes are OK. Waiting your considerations.

[ANF1S]

Hello @agodemar , @seanmcleod70 , I have updated the code and pushed the requested modifications.

While testing:
Problem:

• <engine> and <thruster> path configuration. Obtained Could not open file: J52 when loading aircraft.

Solution:

• Created a folder A4SAS/engine and copied the files direct.xml and J52.xml into it.

Please let me know if this implementation looks good to you or if you would prefer any further adjustments.

[agodemar]

@ANF1S are you sure the engine shouldn't be at the same level of examples/python? Besides examples/python/aircraft

Moreover, what about:

PATH_TO_JSBSIM_FILES= "."

[seanmcleod70]

@agodemar the engine folder can be in either, i.e. at the same level as aircraft, which makes the engine available to all aircraft, or privately as a sub-directory of the specific aircraft. JSBSim has logic to look in both locations.

[ANF1S]

@agodemar , @seanmcleod70 thanks for the feedback. Locally , I tested

• PATH_TO_JSBSIM_FILES= "." and works fine in the current directory

• For engine, the path should be examples/python/engine

I will update those modifications

[seanmcleod70]

Yep, I just downloaded the notebook, the FDM, engine etc. and tested locally.

I tested both of the following and both worked.

  PATH_TO_JSBSIM_FILES= "./"
  PATH_TO_JSBSIM_FILES=os.getcwd()

I'd suggest leaving the engine directory as a sub-directory of aircraft\A4SAS in terms of it being somewhat self-contained.

[seanmcleod70]

I haven't tried Google Colab yet. That's going to be a bit trickier in terms of getting the aircraft directory copied over into Colab.

[seanmcleod70]

Looks like 2 main options to get the aircraft data files into Colab, clone the whole repo, seems a bit wasteful, or add some manual directory creation and remote file copying along these lines:

!mkdir aircraft
!cd aircraft
!mkdir A4SAS
!cd A4SAS
!wget https://github.com/JSBSim-Team/jsbsim/blob/master/aircraft/A4/A4.xml

[seanmcleod70]

Hmm, after some further testing, it looks like I was having issues trying to cd within Colab.

So without cd, make use of the -P option of wget.

!mkdir aircraft
!mkdir aircraft/A4SAS
!wget -P aircraft/A4SAS/ https://github.com/JSBSim-Team/jsbsim/blob/master/aircraft/A4/A4.xml

[seanmcleod70]

@ANF1S in terms of the filename, currently test_pitch_sas.ipynb I'd suggest giving it a more friendly looking name along the lines of some of the other examples, so maybe Pitch SAS Implementation.ipynb.

There seem to be a couple of statements that have been copied over from an existing example that aren't relevant for this example:

from pathlib import Path

# IC references TAS, comment mentions CAS
fdm['ic/vt-kts']    = 250  #calibrated airspeed (kts)

print("Trim failed, continuing rudder kick in an untrimmed state.")

[ANF1S]

Thanks for the review @seanmcleod70 . I fixed those lines and also changed the name of the notebook. About engine , it stays as subdirectory of aircraft/A4SAS as suggested.

[seanmcleod70]

@ANF1S thanks. So from my side the only outstanding thing is the Google Colab support. If the notebook is going to support being launched from the repo into Colab then we need to make sure it works, or we need to remove the Colab support.