| Travis CI (Linux) | AppVeyor CI (Windows) |
|---|---|
 |
User Guide | Developer Docs | FAQ | Contact | Legal notice
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) for testing and study, or integrated with FlightGear or other flight simulator.
Features include:
- Fully configurable flight control system, aerodynamics, propulsion, landing gear arrangement, etc. through XML-based text file format.
- Rotational earth effects on the equations of motion (Coriolis and centrifugal acceleration modeled).
- The earth atmosphere is modeled according to the International Standard Atmosphere (1976)
- Configurable data output formats to screen, file, socket, or any combination of those.
More information on JSBSim can be found at the JSBSim home page here:
Win64 executables for JSBSim are available in the JSBSim project release section. There are 2 executables:
JSBSim.exewhich runs FDM simulations.aeromatic.exewhich builds aircraft definitions from Question/Answer interface
Both executables should be used from the console.
Debian packages for Ubuntu Linux "Trusty" 14.04 on 64 bits platform are also available in the JSBSim project release section. There are 3 packages:
JSBSim_1.0.0-xxx.trusty.amd64.debwhich installs the executablesJSBSimandaeromaticJSBSim-devel_1.0.0-xxx.trusty.amd64.debwhich installs the development resources (headers and libraries)pythonX-JSBSim_1.0.0-xxx.trusty.amd64.debwhich installs the Python module of JSBSim (for python 2.7 if the package name starts with python2 or 3.4 if it starts with python3)
At the moment, JSBSim do not provide binaries for platforms other than Windows 64 bits and Ubuntu 14.04 64 bits. If you fall in this category you should follow the instructions in the developer docs to build JSBSim on your platform.
You can get aircraft data and example scripts by downloading either the zip package or the tar.gz package.
Once you have downloaded (or built) the binaries and unzipped the aircraft data. Go to the root of the data package and make sure the executable is accessible from there.
You can then run an FDM simulation with the following command:
> JSBSim.exe --script=scripts/c1721.xmlMore options are available if you run:
> JSBSim.exe --helpA first place to look at for JSBSim documentation resources is http://jsbsim.sourceforge.net/documentation.html. This link points to the official JSBSim Reference Manual, a PDF which is the best source of information for users and developers.
However, due to the nature of the development of the project (JSBSim sources are updated often, sometimes even daily), several new features that are available in the software are not yet documented in the reference manual. Starting from March 2018 a new effort is underway to deliver an up-to-date documentation web site. You can browse the new JSBSim Online Reference Manual by going to: https://jsbsim-team.github.io/jsbsim-reference-manual. The online manual is under construction and as a first milestone it will incorporate all the non-outdated material contained in the original PDF Reference Manual. The online manual web site is based on the GitHub Pages technology and its sources are available here. Eventually, the PDF Reference Manual will be superseded by the online manual, which is designed to be updated collaboratively as well as in efficient and timely fashion.
JSBSim can be interfaced or integrated to your application via a C++ API. The following code illustrates how JSBSim could be called by a small program, with execution being controlled by a script:
#include <FGFDMExec.h>
int main(int argc, char **argv)
{
JSBSim::FGFDMExec FDMExec;
bool result = true;
FDMExec.LoadScript(argv[1]);
while (result) result = FDMExec.Run();
}The API is described in more details in the C++ API documentation
Source Code | Build | Tests | Installation | Packaging | C++ API
The GitHub repository of JSBSim is reachable at this link: github.com/JSBSim-Team/jsbsim.
You need to have the Git software installed. Git is a version control software, a system that records changes to a file or set of files over time so that you can recall specific versions later. The JSBSim software source code files are being version controlled by Git.
To install Git go to its download site and grab the version for your platform. You can choose to use Git locally on your computer in two ways: via one of the GUI clients, or through a command shell (e.g. a Bash shell on Linux or Windows).
Once you have installed Git, assuming you are going to use Git from the command shell, the JSBSim source code public repository can be cloned from GitHub
The Git command to clone the repo is (HTTPS mode)
> git clone https://github.com/JSBSim-Team/jsbsim.git jsbsim-codeor (SSH mode)
> git clone git@github.com:JSBSim-Team/jsbsim.git jsbsim-codeJSBSim can either be built with CMake or Microsoft Visual Studio. If you are using a Mac OSX or a Linux platform, you must use CMake. If you are a Windows user you can use either one.
JSBSim is coded in standard C++11/C99 and has no dependencies, so all you need is a C/C++ compiler installed on your platform.
CMake is a multiplatform tool to build and test software. It can produce files to build JSBSim with GNU make or Microsoft Visual Studio. To keep the build files separated from the source code, it is preferable to build JSBSim in a separate directory.
> cd jsbsim-code
> mkdir build
> cd buildCMake does not build software, it produces files for a multitude of build tools. The following commands are assuming that you are using GNU make to build JSBSim.
First, you should invoke CMake and then execute make
> cmake ..
> makeThis will compile the various classes, and build the JSBSim application which will be located in build/src
CMake can use a number of parameters to tune the build of JSBSim. Different options are presented below. You can use them independently or any combination thereof depending on your needs.
If you want to set compiler options, you can pass flags to CMake to build a Debug version of JSBSim. JSBSim also uses C for some code, you can set options for both the C++ and the C compiler.
> cmake -DCMAKE_CXX_FLAGS_DEBUG="-g -Wall" -DCMAKE_C_FLAGS_DEBUG="-g -Wall" -DCMAKE_BUILD_TYPE=Debug ..
> makeOr alternatively you can build a Release version of JSBSim and request GNU Make to use 4 cores to build the executable faster.
> cmake -DCMAKE_CXX_FLAGS_RELEASE="-O3 -march=native -mtune=native" -DCMAKE_C_FLAGS_RELEASE="-O3 -march=native -mtune=native" -DCMAKE_BUILD_TYPE=Release ..
> make -j4JSBSim uses the Expat library to read XML files. The Expat source code is provided with JSBSim source code and is compiled along with JSBSim during its build. However, if Expat is already installed on your platform you might prefer to use your system Expat library in order to avoid duplication. In that case, you should pass the SYSTEM_EXPAT flag to CMake:
> cmake -DSYSTEM_EXPAT=ON ..
> makeMost of JSBSim code can be built as a shared library, so that the executable JSBSim and the Python module can share the same library which reduce the memory and disk space consumption.
The option BUILD_SHARED_LIBS must then be passed to CMake
> cmake -DBUILD_SHARED_LIBS=ON ..
> makeA Python module of JSBSim can also be built by CMake. For that, you need Cython installed on your platform. CMake will automatically detect Cython and build the Python module.
From Visual Studio, you can open the project file JSBSim.vcxproj to open a project for JSBSim. The project file will setup Visual Studio for building the JSBSim executable.
Note 1: JSBSim official build tool is CMake. Visual Studio project files are provided as a convenience and are not guaranteed to be up to date with the code.
Note 2: Since Visual Studio 2017, Microsoft has included CMake so you can build JSBSim on VS2017 directly from the CMake file.
For more detailed instructions on using Visual Studio project files and CMake via Visual Studio to build JSBSim take a look at the following documentation link - Building using Visual Studio.
JSBSim comes with a test suite to automatically check that the build is correct. This test suite is located in the tests directory and is coded in Python so you need to build the Python module of JSBSim first.
The tests are also using numpy, pandas and scipy so you need these Python modules to be installed on your system.
The test suite can then be run using ctest in the build directory. Tests can also be run in parallel on several cores (4 in the example below) using the option -j
> ctest -j4Once JSBSim is built and tested, you can install the C++ headers and library. For that, you can invoke GNU make from the build directory
> make installBy default, CMake copies the files to a location where the headers and library are available platform wide (typically /usr/include, /usr/lib or /usr/local/include, /usr/local/lib for *nix OSes). If you want to install the files in another location you can pass the flag CMAKE_INSTALL_PREFIX to cmake.
cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
make
make installIf you plan to install the Python module of JSBSim in addition to the C++ headers and library, then you must pass the flag INSTALL_PYTHON_MODULE to CMake. This is the procedure you should follow if you plan to package JSBSim with CPack.
> cmake -DINSTALL_PYTHON_MODULE=ON ..
> make
> make installNote: make install will attempt to override Python virtual environments in order to install the Python module platform wide (i.e. in a directory such as /usr/lib/python). If you want the Python module installation process to comply with your virtual environment, you should use the Python distutils as described below.
Alternatively, the Python module can be installed manually by invoking the Python distutils from the build directory. The installation will ignore the option CMAKE_INSTALL_PREFIX and will be performed even if INSTALL_PYTHON_MODULE has not been set to ON.
This is the procedure you should follow if you are using Python virtual environments.
> python python/setup.py install --skip-buildThe option --skip-build avoids to rebuild the module.
JSBSim can also be packaged for releases. This is done automatically by Travis CI for the Ubuntu 14.04 LTS platform and the resulting Debian packages are available for download on the JSBSim GitHub project page.
The packaging can be done by passing the option CPACK_GENERATOR to CMake then invoking CPack.
At the moment, only RPM and Debian packages are supported by JSBSim.
> cmake -DCPACK_GENERATOR=DEB .. # or RPM
> make
> cpackThe following packages are then built (with the extension .rpm if you selected the RPM generator)
JSBSim_[version].[platform].[architecture].debwhich contains the executablesJSBSimandaeromatic(and shared libraries ifBUILD_SHARED_LIBSwas set toON)JSBSim-devel_[version].[platform].[architecture].debwhich contains the files for C++ development headers (and the static library ifBUILD_SHARED_LIBSwas not set toON)python[2-3]-JSBSim_[version].[platform].[architecture].debwhich contains the JSBSim Python module ifINSTALL_PYTHON_MODULEwas set toON
The JSBSim C++ API documentation is built from the source code with Doxygen and is automatically published on GitHub each time a commit is pushed to the JSBSim GitHub project. It can be viewed here:
https://jsbsim-team.github.io/jsbsim/.
If you modify the documentation, you might need to generate the documentation locally in which case you should run the following command after cmake has been executed
> make docThe HTML documentation will then be available in the directory build/documentation/html. Note that you need Doxygen and Graphviz to be installed.
Q: I ran ctest from my build directory and it reports one or several tests failures. The problem is that ctest does not seem to give any details about the reason why the tests failed.
A: All the output issued by tests run by ctest are logged in the file Testing/Temporary/LastTestsFailed.log.
Q: One of the tests ran by ctest is failing and I am trying to debug it. But ctest always executes all the tests and it takes much time. To iterate faster, I would like to focus only on the test that fails. How do I tell ctest to skip all the tests but the test that fails ?
A: You can filter the tests executed by ctest with the options -R, -E and -I. Say you want to run exclusively TestDensityAltitude.py then you can use the following command
> ctest -R TestDensityAltitudeIf you need to run all the tests which name contains Altitude, you can use
> ctest -R AltitudeIf you need to run all the tests but thoses which name contains Altitude, you can use
> ctest -E AltitudeIf you need to run tests #12 to #14, you can use
> ctest -I 12,14You can find more informations about ctest from its manual page
Q: Before running make install, I want to execute ctest but all the tests fail. And when I check in the file Testing/Temporary/LastTestsFailed.log it reports many errors such as
31: Traceback (most recent call last):
31: File "TestTurbine.py", line 23, in <module>
31: from JSBSim_utils import JSBSimTestCase, CreateFDM, RunTest, append_xml
31: File "/xxx/build/tests/JSBSim_utils.py", line 24, in <module>
31: import jsbsim
31: ImportError: libJSBSim.so.1: cannot open shared object file: No such file or directory
A: This error means that the library loader cannot find the JSBSim shared library (libJSBSim.so.1) so you must tell it where it is located. For that purpose, you can use the environment variable LD_LIBRARY_PATH like below
> LD_LIBRARY_PATH=$PWD/src ctestThe command above will succeed if you execute it from your build directory in which case the environment variable PWD will contain the path to your build directory.
For more information on JSBSim, you can contact the development team on the mailing list jsbsim-devel@lists.sourceforge.net or submit tickets on https://github.com/JSBSim-Team/jsbsim/issues
We are also on Facebook: https://www.facebook.com/jsbsim/
JSBSim is open source and is licensed under the LGPL 2.1 license. The license is included in the source code in the file COPYING
No proprietary code is included. All code included within JSBSim has been developed on a volunteer basis using publicly available information, and is often directly linked to a particular textbook, for educational reference. In some cases, code of a generic nature has been donated back to the project.
Likewise, the aircraft models included in this project and distribution do not include any proprietary, sensitive, or classified data. All data is derived from textbooks (such as Stevens and Lewis "Aircraft Control and Simulation" and Sutton's "Rocket Propulsion Elements"), freely available technical reports (see: http://ntrs.nasa.gov and http://www.aiaa.org), or other public data (such as the FAA web site). Aircraft models included in the JSBSim distribution and with names corresponding to existing commercial or military aircraft are approximations crafted using publicly available information, and are for educational or entertainment uses only.