Adding google colab links of examples to README

[yuki-2000]

Hello.

I just find this great project and I wonder if people who find this project for the first time could more easily try these example programs.
The README file provides a great quick start guide, but beginners need to type in a few commands to download, move folders, and run files.

How about adding a Google Colab link like below to the ReadMe file?

As you may know, but in case you don't, google colab is a hosted Jupyter Notebook service that requires no setup to use and provides free of charge access to computing resources, including GPUs and TPUs.
Simply click the Run buttons and we can download and run the example file independently of our environment.

Now this icon link to the my personal google drives file based on examples/python, but you can change this to this github repository's file.

I would appreciate it if you could share your thoughts.

Thank you.

[seanmcleod70]

Yes I think this would be a useful addition. Some percentage of users will be happy enough just to view the static Jupyter notebook rendering on Github but some may well want to run it themselves to tweak some of the options etc. but without the hassle of installing and doing all that locally.

I last used Google Colab a number of years ago, so I'm a bit rusty. Wouldn't we (JSBSim organization) need to provide a Google Drive for the repo to be checked out to etc. unless the user already had their own Google Colab setup?

[yuki-2000]

Thank you for your comment.

You do not have to provide a Google Drive or some other annoying things.
All you have to do is upload .ipynb file to github repository and set the url like
https://colab.research.google.com/github/JSBSim-Team/jsbsim/blob/master/examples/python/AoA%20vs%20CAS.ipynb

The below icon can open the file of examples/python with google colab. (not correctory working because of lack of git clone or pip command.)
Maybe users have to use their own google account to run the google colab, but this is not a big problem.

To sum up,

1. upload ipynb file which add below three command in the head of existing example python file

!git clone https://github.com/JSBSim-Team/jsbsim.git
!pip install jsbsim
%cd jsbsim/examples/python

2. make a link like https://colab.research.google.com/github/JSBSim-Team/jsbsim/blob/master/[path_to_the_file]
3. set the link with the icon like [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)]({above_link])

you can provide google colab trial version.

[seanmcleod70]

Okay, when I used your link earlier and ran the cell with the magic to perform the git clone, pip install etc. I wasn't sure if the storage space for them was being provided via your Google Drive.

Is there a conditional magic command?

If we add the following as the first cell of every Jupyter notebook, then someone who downloads the Jupyter notebook, directly or via a git clone of the JSBSim repo to their own PC will end up with another JSBSim repo installation.

!git clone https://github.com/JSBSim-Team/jsbsim.git
!pip install jsbsim
%cd jsbsim/examples/python

[yuki-2000]

1. With Google Collab, Google allocates temporary storage to users. Each time it is restarted, the storage is fresh. You can link to Google Drive if you want, but it requires a special command. Therefore, files that you Git clone or Pip install on Google Colab will be stored in temporary storage, not in a specific user's Google Drive. No one have to care the storage management.

2. As you pointed out, this could cause confusion for those who have downloaded JSBSim and run this Jupiter Notebook, such as downloading JSBSim again. (I don't know if !git or !pip will work locally outside of google colab by the way). Therefore, we propose to add an additional google colab folder and an additional Jupiter notebook, separate from the existing Jupiter notebook.

I believe that it is important for beginners to try JSBSim easily and quickly, and the complicated steps of installation and building should be omitted for beginners.

[seanmcleod70]

The ! option in Jupyter notebooks allows you to run any shell command, i.e. they're not specific to Google Colab. So if git and pip are on the path on the user's local system they will execute locally.

FYI - What is the difference between ! and % in Jupyter notebooks?

I believe that it is important for beginners to try JSBSim easily and quickly, and the complicated steps of installation and building should be omitted for beginners.

I agree. It's just a question of the best option in terms of supporting both Google Colab and users wanting to use the Jupyter notebooks locally. There are some downsides to having to maintain 2 virtually identical copies each time of new notebook is added or a notebook is edited. That's why I was wondering whether there is some conditional logic we can add to this initial cell to handle both cases.

[yuki-2000]

There are some downsides to having to maintain 2 virtually identical copies each time of new notebook is added or a notebook is edited.

That's True.
Further research revealed the following website:
https://stackoverflow.com/questions/53581278/test-if-notebook-is-running-on-google-colab

Following this logic, I could change the ipynb code.

import sys
if 'google.colab' in sys.modules:
    !git clone https://github.com/JSBSim-Team/jsbsim.git
    !pip install jsbsim
    %cd jsbsim/examples/python

You can try this below link.
https://colab.research.google.com/drive/1Oz8VFg-5yLDL93DmLgr233x0f5NDGjMQ?usp=sharing

I have confirmed that this code runs in google colab and not in my local environment.

How about this way?

[seanmcleod70]

Yep, that was the sort of conditional logic I was looking for.

May want to have an additional check in the conditional logic to see if JSBSim has already been installed, i.e. in other words when the user re-runs the cell manually, or this cell gets run again if they tell Jupyter to re-run all cells etc.

Hmm, I just clicked on your link and saw this output, which seems to be implying that the cell had already been run. Sort of appears that Colab didn't spin up a new instance with new empty temporary storage?

Ah, I think I know what happened. You ran the cell twice in your instance, and so your saved notebook had those messages as the default snapshot rendering when I opened it.

[seanmcleod70]

Hmm, so I tested what happens if I re-execute that first cell, I don't actually get the exact same output as I showed from your notebook above. It's actually worse. This is the output after the 4th run of the cell.

So git isn't complaining that there is already a jsbsim directory, because of the %cd jsbsim/examples/python what is happening is that the second time the cell is run, it does a git clone into:

jsbsim/examples/python/jsbsim

And this continues happening each time it's run. It does pickup that the JSBSim python module is already installed.

[seanmcleod70]

Here is an option to avoid the issue with running the cell multiple times.

try:
  import jsbsim
except ImportError:
  import sys
  if 'google.colab' in sys.modules:
      !git clone https://github.com/JSBSim-Team/jsbsim.git
      !pip install jsbsim
      %cd jsbsim/examples/python
      %pwd

[yuki-2000]

Thanks for correcting the code. I have tried it again and it seems to work fine.
https://colab.research.google.com/drive/1Oz8VFg-5yLDL93DmLgr233x0f5NDGjMQ?usp=sharing#scrollTo=D8TY2bevrk9O

So, regarding the suggestion to add a google colab link, has the issue been all solved?

[seanmcleod70]

Here is my, hopefully last, suggestion:

# Confirm that JSBSim is installed. If not and running on Google Colab
# then install JSBSim into the Google Colab instance.
try:
  import jsbsim
  print('JSBSim is installed')
except ImportError:
  import sys
  if 'google.colab' in sys.modules:
      print('Installing JSBSim...')
      !git clone https://github.com/JSBSim-Team/jsbsim.git
      !pip install jsbsim
      %cd jsbsim/examples/python
print('Current working directory:')
!pwd

In terms of adding the changes to support Google Colab etc. are you interested and willing to submit a Github PR (Pull Request) or do you want one of the JSBSim maintainers to create the PR?

@agodemar, @bcoconni any comments/suggestions?

[yuki-2000]

Actually, I have never submitted a merge request for an official project like this, but I would like to try it as an experience.
I will take a look at this document and past pull requests. It may take some time, so please wait.
https://github.com/JSBSim-Team/jsbsim/wiki/Contributing-Source-Code-Changes-to-JSBSim

I am planning to change:

1. Adding the following code to the first cell of each code block of examples/python

# Confirm that JSBSim is installed. If not and running on Google Colab
# then install JSBSim into the Google Colab instance.
try:
  import jsbsim
  print('JSBSim is installed')
except ImportError:
  import sys
  if 'google.colab' in sys.modules:
      print('Installing JSBSim...')
      !git clone https://github.com/JSBSim-Team/jsbsim.git
      !pip install jsbsim
      %cd jsbsim/examples/python
print('Current working directory:')
!pwd

2. Adding the explanation that it can be opened in Google Colab and add google colab link to README

Python module examples

The examples/python directory contains a number of example Python based scripts embedded in Jupyter notebooks demonstrating the use of JSBSim to determine and analyse aircraft performance.
You can also quickly try it out using Google Colab by clicking on the icon.

• AoA vs CAS.ipynb calculates and plots the AoA (Angle of Attack) versus CAS (Calibrated Air Speed) for level trim for a range in aircraft weight, altitude and cg (center of gravity).
  

• Trim Envelope.ipynb calculates a set of trim points for an aircraft over a range of airspeeds and flight path angles. Required thrust and AoA is indicated via a colormap.
  

• Rudder Kick.ipynb simulate a pilot performing a rudder kick test with time histories of the control inputs and sideslip angle plotted.
  

• Thrust Vectoring Analysis.ipynb vary the thrust vector angle to determine the minimum fuel burn for cruise and climb conditions.
  

3. Option : Add an explanation and link to the introduction in the readme. People visiting the repository for the first time are unlikely to read through the entire readme. The google colab icon may attract their attention and encourage them to try it out.

Introduction

JSBSim is a multi-platform, general purpose object-oriented Flight Dynamics Model (FDM) written in C++. The FDM is essentially the physics & math model that defines the movement of an aircraft, rocket, etc., under the forces and moments applied to it using the various control mechanisms and from the forces of nature. JSBSim can be run in a standalone batch mode flight simulator (no graphical displays a.k.a. console mode) for testing and study, or integrated with the Unreal engine, FlightGear and many other simulation environments.

Features include:

• Nonlinear 6 DoF (Degree of Freedom)
• Fully configurable flight control system, aerodynamics, propulsion, landing gear arrangement, etc. through XML-based text file format.
• Accurate Earth model including:
  • Rotational effects on the equations of motion (Coriolis and centrifugal acceleration modeled).
  • Oblate spherical shape and geodetic coordinates according to the WGS84 geodetic system.
  • Atmosphere modeled according to the International Standard Atmosphere (1976).
• Configurable data output formats to screen, file, socket, or any combination of those.

JSBSim also includes the following bindings:

• A Python module which provides the exact same features as the C++ library. -Easy testing of simulations on Goole Colab.
• A Matlab S-Function that interfaces JSBSim with MATLAB Simulink.
• An Unreal Engine plugin to build a connection between the flight dynamics model from JSBSim and the entire virtual environment provided by Unreal engine.

please give me your opinions.

[seanmcleod70]

Actually, I have never submitted a merge request for an official project like this, but I would like to try it as an experience.

No problem, we encourage new users to contribute.

I will take a look at this document and past pull requests. It may take some time, so please wait.

No rush. Yes, please read the contribution document, and if there isn't something that is clear enough then ask here and I can update the contribution document if need be.

Adding the following code to the first cell of each code block

I'd suggest adding it as it's own separate cell block, rather than adding it to the contents of the existing first cell block.

A Python module which provides the exact same features as the C++ library. -Easy testing of simulations on Goole Colab. Open In Colab

For this Google Colab link in the introduction, rather than linking to one specific notebook to open in Colab, rather use the generic Colab icon/image but make it a link to the Python module examples header, i.e. so if the click on the Google Colab link image they'll jump down to this section and then see 4 current examples each with a "Open in Colab" link at the end of each description.

Rest of the suggestions look good to me.

[yuki-2000]

This suggestion was adopted in #1309

Thank you for your support, @seanmcleod70.
I hope this project will become even better.

[agodemar]

Thank you for quicly adding this feature. Here's a post I made on my LinkedIn wall.

Lowering the entry lever for new JSBSim users continues...