OpenRocket wiki - User contributions [en]

Scripting with Python and JPype

2016-03-17T07:35:58Z

Justgerrardz:

== Scripting openrocket with Python and JPype ==

The ability to script openrocket and enhance it with user written code is an often discussed topic among the openrocket community.
This article demonstrates one approach to the problem. Using python [http://python.org] and the jPype [http://jpype.sourceforge.net/] library it is possible to write external scripts which run outside of openrocket, but make use of openrocket much like any other python library.

This approach provides a very rapid development environment for optimising rocket designs, enhancing and exploring the simulation. It is also probably the best approach if you are interested in making use of openrocket as part of something larger. An important advantage to this approach over something like embedded Jython scripting is that you have full access to all the python ecosystem, crucially numpy [http://numpy.scipy.org/], scipy [http://scipy.org], matplotlib [http://matplotlib.sourceforge.net] and other cpython only libraries. However, because scripts require external software they can not be integrated into a stand-alone openrocket distribution. Nevertheless, they do provide a nice way to prototype new openrocket features.

=== Requirements ===

To run the following examples you will need python 2.5 or later python 2.x version, jpype, and an Openrocket .jar > 1.19. The numpy, scipy, matplotlib libraries are required (these usually come together). These scripts all make use of a python module ''orhelper.py'' (below).

Note: Until we find a better way to host the files, they can be downloaded from the [https://sourceforge.net/mailarchive/forum.php?thread_name=4F17AA0C.1040002%40rdg.cc&forum_name=openrocket-devel mailing list archive].
[http://www.rushtonfinancial.com.au Best Investment] | [http://www.rushtonfinancial.com.au/why-invest Managed Funds] | [http://www.rushtonfinancial.com.au/about-us Mutual Funds Australia]

=== Orhelper : ''[[File:orhelper.py]]'' ===

This is a fairly lightweight module which has been written for these examples to take care of some of the more cumbersome aspects of scripting openrocket with jpype.
At the time of writing the orhelper module contains:
# a class ''OpenRocketInstance'' which handles starting up a JVM and a working [http://www.papdan.com/ Melbourne Web Developer], [http://www.papdan.com/seo-services-search-engine-optimisation.php Melbourne SEO Services] openrocket instance. It is equip with ''__enter__'' and ''__exit__'' methods and is intended to be called using the 'with' construct [http://effbot.org/zone/python-with-statement.htm] of python 2.5. This is to ensure that no matter what happens within that context, the JVM will always properly shutdown and you will get useful (hopefully) exception information.
# a class ''Helper'' which simply contains a bunch of useful helper functions and wrappers for using openrocket via jpype. These are intended to take care of some of the more cumbersome aspects of calling methods, or provide more 'pythonic' data structures for general use. The whole ''net.sf.openrocket'' namespace is available as the ''orp'' property of this class.
# an ''AbstractSimulationListener'' class. This is essentially a python version of the ''openrocket.simulation.listerners'' class of the same name. You can extend this class to make your own python simulation listeners and receive callbacks from the openrocket simulation.
# there is also a little wrapper class in there, ''JIterator'' which is for using java iterators as if they are python iterators.

=== Example 1 : ''[[File:simple_plot.py]]'' ===

This is a simple example for plotting the flight of a rocket using matplotlib. A plot of altitude and vertical velocity vs time is generated, with annotations for various events much like the default plot in openrocket.

In this example all the interaction with openrocket is done through various Orhelper methods. The orhelper.Helper class will from now on be referred to as orh.

First, we startup an openrocket instance inside the protected 'with' environment. Be sure to change the name of the openrocket .jar file accordingly.
We then load up an openrocket document, I am using the 'simple model rocket example' here. We then grab a simulation object out of this file. This file has multiple simulations set up, we just get the first one. We then run the simulation. We now need to get the data out of the simulation. This is done with the ''orh.get_timeseries'' method. This returns dictionary of timeseries data (as numpy arrays) from a simulation given a sequence of variable names. Variable names are as according to the default locale, check inside the openrocket plot window for the exact names. For adding annotations to the plot, we need to get a dictionary containing all the flight events. This is done with ''orh.get_events'' (keys are the names of the events and values are the times).

The rest of the code is standard matplotlib stuff -- check their documentation if you are not familiar [http://www.phillro.com.au/p/industrial-2/airless-spray-packages-2/ Airless Spray]. A couple of the inline functions though are worthy of further explanation. I wanted to have the axis labels and tick marks the same colour as the lines. Matplotlib doesn't have a built in way to change all the tickmarks, but that is easily done with the in line function ''change_color''. Also, because get_events only gives us time information we need to extract the corresponding array index to put the annotations in the correct place. This done with the ''index_at'' function which in turn makes use of the numpy ''argmin'' [http://www.oxone-online.com Oxone] function.

[[File:simple_plot.png]]

=== Example 2 : ''[[File:lazy.py]]'' ===

The purpose of this example is to show how a simulation can be modified and demonstrate the use of scipy's numerical methods. The toy problem we are attacking is the one of the rocketeer of maximum laziness who does not want to walk from the launch site to collect the rocket and would prefer if it flew exactly back of its own accord. We assume the rocket is flying upwind and optimise the launch rod angle accordingly. We want to plot a family of curves for a few different angles and highlight the optimised angle.

The structure of the program and initial lines for loading the model rocket are the same as in the previous example. In this example, we need to define a function for varying the launch angle before simulating the flight. This requires us to get the simulation options out of the simulation using the ''getOptions()'' method and we can then set the angle inside the ''SimulationOptions'' object. For the uninitiated, in openrocket ''simulation.SimulationOptions'' basically contains all the settings found in the simulation edit window. When the simulation is started these options are used to make a ''simulation.SimulationConditions'' object. After running the simulation we are interested in the 'Altitude' and 'Position upwind' variables. One option would be to just retrieve the final values with ''orh.get_final_values'', however for reasons that will shortly become clear we have retrieved the whole time series.

For running an optimisation method, we need some function which is zero at the optimum point. This is not quite as simple as just getting the final upwind distance because the simulation stepper will usually slightly overshoot and calculate a final point with a negative altitude. We also want to exclude the launch. There are more elaborate ways this could be done --- here for simplicity we just slice out the last half of the data, find the index with the smallest absolute altitude and return the corresponding upwind distance. We can then go ahead and pass this to our optimisation method, giving some initial guess (40 deg) to start with. Scipy has a wide range of optimisation methods with a rich heritage, in our case we just choose the basic ''fmin'' which uses the downhill simplex algorithm.

In this example we want to plot a family of curves as well so we generate a range of 10 launch angles with ''np.linspace'' and add our optimal angle. We then run the simulations, making a list of all the timeseries data dictionaries and adding an 'Angle' key to each dictionary. We then go ahead and plot this, using a solid line style for the optimal curve and dashed lines for the others.

[[File:lazy.png]]

=== Example 3 : ''[[File:monte_carlo.py]]'' ===

As every student of introductory physics knows, presenting just a number as the result of a calculation is not really sufficient -- we also need to know the uncertainty to make it meaningful. The purpose of this example is to demonstrate a simple monte carlo method [http://en.wikipedia.org/wiki/Monte_Carlo_method] where multiple simulations are run with various parameters perturbed to determine an overall uncertainty for the landing location in terms of range and bearing from the launch site. This example also demonstrates the use of simulation listeners implemented in python. Openrocket simulation listeners are covered in [[Simulation_Listeners|section 9 of the users guide]].

The structure of this script is slightly different from the previous examples. First consider how we get the landing range and bearing information. This information is not available directly as a simulation variable, although latitude and longnitude are. One option would be to get these variables and do the calculation in python. However, openrocket already includes methods to do this as part of ''util.GeodeticComputationStratery'' which is a parameter of each simulation, so it is nice to make use of these which operate natively on ''util.WorldCoordinate'' objects. We do this by defining a new simulation listener ''LandingPoint'' which extends ''orhelper.AbstractSimulationListener''. We define an ''endSimulation'' method which grabs the simulation ''GeodeticComputationStratergy'' and uses it to find the range and bearing from the lanuch site ''WorldCoordinate'' (from ''SimulationConditions'') to the rocket position (from ''SimulationStatus''). These are saved as ''LandingPoint'' instance variables.

Multiple ''LandingPoint'' objects are stored in a ''LandingPointList'', which is like a regular list except can populate itself with landing points by running multiple openrocket simulations. Various parameters are set by choosing from a gaussian distribution with given mean and standard deviation (pythons ''random.gauss'' method). The code for running the simulations has mostly been discussed earlier, and the same example rocket is used although in my case I turned up the wind and turbulance somewhat and switched to a spherical earth computation method. One aspect that is new is the modification of the rocket model. A ''rocketcomponent.Rocket'' object can be obtained from the simulation options. This is the root of a tree type data structure containing all the rocket components. Our ''orh.Helper'' class has a method for finding components in the tree given their names. We use this to obtain the nose cone and body tube components and override their masses with perturbed values. Running the simulation is again done using ''orh.runsimulation'', except in this case we pass in a sequence of listener objects to use. To increase the variability still we pass in a ''AirStart'' listener with randomly set start altitude. This listener is a python copy of the example supplied with openrocket.

Finally, when run the main function of the script makes a new ''LandingPointList'', populates it and then uses the ''print_stats'' method to show the final landing statistics, something like:

<code>Rocket landing zone 3833.57 m +- 1116.91 m bearing -89.98 deg +- 0.0713 deg from launch site. Based on 20 simulations.</code>

Note that it might take a minute or two to run all those simulations.

Developer's Guide

2016-03-17T07:20:42Z

Justgerrardz:

{{Access}}

This page contains information on the inner workings of OpenRocket and is meant primarily for developers interested in developing OpenRocket.

In addition to this page, information can be found in the [http://openrocket.sourceforge.net/documentation.html Technical documentation] chapter 5.

== Obtaining the source code ==

OpenRocket is primarily developed using [http://www.eclipse.org/ Eclipse], and it's the recommended IDE for compatibility. Developers are free to use other IDE's, but everything may not work out-of-the-box.

The source code is hosted on [https://github.com/openrocket/openrocket/ GitHub]. You need either to install the [http://www.eclipse.org/egit/ EGit] plugin to Eclipse, or use some other Git client (for example the command-line client).

Using the command-line, the OpenRocket code can be retrieved by:

<pre>
$ git clone git://github.com/openrocket/openrocket.git
</pre>

'''Note:''' The source packages available on the OpenRocket web site (*.zip) are meant for building the application from source code, '''NOT''' for development purposes. They do not contain all the project files etc [http://www.tokobungasabana.com Toko bunga],[http://www.tokobungasabana.com Toko bunga jakarta], [http://trimasjaya.com/products/railing_tangga/index.html Railing Tangga], [http://www.detikauto.com Aksesoris Mobil], [http://www.forklift.co.id Rental Forklift]

== Source ==
* [http://www.pokerworld88.com/ Poker Online]
* [http://www.musimdomino.com/ Domino Online]
* [http://www.texaspoker83.com/ Texas Poker]
* [http://www.specialispoker.com/ Poker Online]
* [http://www.mejapoker88.com/ Poker Indonesia]
* [http://www.dinastipoker.com Agen Domino99]

== Running OpenRocket from Eclipse (tested with Eclipse Luna and OpenRocket v15.03, September, 2015) ==

The following steps should get you up and running with OpenRocket source code: 

1) After downloading the source code, start Eclipse. 
2) From the Eclipse main menu, select File -> Import. 
3) In the Import window that opens, select General -> Existing Projects into Workspace, then click Next. 
4) In the Select root directory field, browse to the location of the OpenRocket source code that you downloaded. 
5) In the file browser that appears, click on the openrocket root project directory. A list of projects should then appear in the Projects pane on the import window. 
6) Select only these three projects from the list: OpenRocket Core, OpenRocket Swing and OpenRocket Test Libraries. (Note: As of v15.03 you no longer need to load the other projects to build OpenRocket on the desktop.) 
7) Once those three projects have been selected, click Finish. Eclipse should start with those three projects shown in the Package Explorer. 

NOTE: You might see errors in some source files, reporting that various Java classes cannot be found. If that happens, you might try these steps to resolve these issues: 

8) In the Project Explorer pane in Eclipse, right-click on the project reporting the errors. Select Properties. 
9) In the properties window that opens, select Java Build Path -> Libraries. 
10) Make sure that the JRE System Library for your version of Java is seen in the list of libraries. 
11) If it is NOT included in the list, click the Add Library button in the menu to the right. 
12) From the Add Library window that appears, select JRE System Library from the list. Then click Next. 
13) Make sure that the correct Workspace is selected in the next window that appears, and then click Finish. Once the Add Library window closes, you should then see the JRE System Library added to the list of libraries in the project properties window. 
14) Click OK. Once the project properties window closes you will be returned to Eclipse, and hopefully the errors reported by the IDE will then resolve. 
15) If there are still errors, you'll need to revert to Google for additional help. Googling the exact error string reported by Eclipse will most likely help you resolve any outstanding dependency issues. 

*** Also note that the main entry point for OpenRocket is in the OpenRocket Swing project, in the net.sf.openrocket.startup.SwingStartup.java file. With that file active OpenRocket should build and start. 

Finally, remember that help is available either in the OpenRocket forums or in the main developers list. Good Luck! 

== Marking TODO's ==

Often when writing code you know that something could be done better, but at the moment is either impossible or unreasonable. These are commonly marked with a TODO comment. The following convension is used to mark the importance of different TODO's:

* <code>// TODO: CRITICAL: Some comment</code> A bug or something that is not yet implemented, and must be corrected before any release is made. The Ant build script checks for these and prevents building if such a comment is found.
* <code>// TODO: HIGH: Some comment</code> An important issue that should be looked into within this or the next major release.
* <code>// TODO: MEDIUM: Some comment</code> Something that would make the software better, but does not represent a problem as such.
* <code>// TODO: LOW: Some comment</code> Something that would be nice to do better in the future

== Debugging ==

=== LogBack ===

As of version 13.05, OpenRocket uses [http://logback.qos.ch/index.html LogBack] for logging.

If you want to change the default logging that OpenRocket uses, you can create or reuse a LogBack configuration file stored in openrocket/core/config. For example, you can use the logback-stdout-level-error.xml there which tells logback to log everything to stdout with logging level of Error (serious errors only).

To enable use of a LogBack configuration file, pass the JVM the following option during startup:

-Dlogback.configurationFile=config/logback-stdout-level-error.xml

See the [http://logback.qos.ch/manual/configuration.html LogBack configuration page] for more details.

=== Probably Obsolete Debugging Info ===

Log messages in openrocket are specified by one of six levels. You can specify which level of errors you want reported to standard out with a system property which you can add to your VM argument, e.g:

-Dopenrocket.log.stdout=debug

The error levels available are:

: '''ERROR''' - Level for indicating a bug or error condition noticed in the software or JRE. No ERROR level events _should_ occur while running the program.

: '''WARN''' - Level for indicating error conditions or atypical events that can occur during normal operation (errors while loading files, weird computation results etc).

: '''USER''' - Level for logging user actions (adding and modifying components, running simulations etc). A user action should be logged as soon as possible on this level. The level is separate so that additional INFO messages won't purge user actions from a bounded log buffer.

: '''INFO''' - Level for indicating general level actions the software is performing and other notable events during execution (dialogs shown, simulations run etc)

: '''DEBUG''' - Level for indicating mid-results, outcomes of methods and other debugging information. The data logged should be of value when analyzing error conditions and what has caused them. Places that are called repeatedly during e.g. flight simulation should use the VBOSE level instead.

: '''VBOSE''' - Level of verbose debug logging to be used in areas which are called repeatedly, such as computational methods used in simulations. This level is separated to allow filtering out the verbose logs generated during simulations, DnD etc. from the normal debug logs.

In the code, the standard way to log errors is with

log.verbose("Error message");

where log is defined in each class as :

private static final LogHelper log = Application.getLogger();

== Units used in OpenRocket ==

OpenRocket always uses internally pure SI units. For example all rocket dimensions and flight distances are in meters, all masses are in kilograms, density is in kg/m³, temperature is in Kelvin etc. This convension is also used when storing the design in the OpenRocket format.

The only exception to this rule is angles:
* Angles are represented as radians internally, but in the file format they are converted to degrees. This is to make the file format more human-readable and to avoid rounding errors.
* Latitude and longitude of the launch site are represented in degrees both internally and externally.

When displaying measures to the user, the values are converted into the preferred units of the user. This is performed using classes in the package <tt>net.sf.openrocket.unit</tt>. The <tt>Unit</tt> class represents a single unit and it includes methods for converting between that unit and SI units in addition to creating a string representation with a suitable amount of decimals. A <tt>UnitGroup</tt> describes a measurable quantity such as temperature and contains the units available for that quantity, such as Celcius, Fahrenheit and Kelvin.

== Rocket design loading and saving ==

''(This section is based on email correspondence)''

All file reading/writing is performed in the package
<tt>net.sf.openrocket.file</tt> and subpackages. To implement a new
document loader it is necessary to extend the class <tt>RocketLoader</tt> and
implement the abstract method <tt>loadFromStream(InputStream)</tt>. This
method simply loads the document and returns an <tt>OpenRocketDocument</tt>
object.

An <tt>OpenRocketDocument</tt> contains all the information about an opened
document, primarily the rocket structure and the simulations. The
rocket structure is a simple tree-like structure of <tt>RocketComponents</tt>.
All of the components are in the package <tt>.rocketcomponent</tt>. A diagram
of their hierarchy and a short explanation of each class is available
in my thesis section 5.1
(http://openrocket.sourceforge.net/documentation.html)

I've implemented a simple XML reading framework (based on SAX), which
simplifies reading by assuming that XML elements can contain only
other elements or text content, but not both. Both the OpenRocket and
Rocksim format abide with this restriction.

The framework is in the package <tt>.file.simplesax</tt>. The primary class
that will be extended is <tt>ElementHandler</tt>, which contains three methods.
<tt>openElement()</tt> is called when a new subelement is found, and it
returns a new <tt>ElementHandler</tt> to handle that element (which can be the
object itself), or <tt>null</tt> in order to ignore that element and all of its
contents (for example for unknown elements). <tt>closeElement()</tt> is called
when the subelement ends, and <tt>endHandler()</tt> is called when the element
of the current handler ends. The JavaDoc should provide the necessary
details.

There are a few ready handlers, the most useful of which will probably
be <tt>PlainTextHandler</tt>. This handler accepts only text content and
ignores all subelements. If the XML file contains
<nowiki><element>value</element></nowiki>, then the handler can return a
<tt>PlainTextHandler</tt> and handle the content within the <tt>closeElement()</tt>
method, removing the need to write a specialized handler for that
element.

The XML reading is initiated by calling <tt>SimpleSAX.readXML()</tt> with the
input source and the initial <tt>ElementHandler</tt>.

The OpenRocket document loading is implemented in
<tt>.file.openrocket.OpenRocketLoader</tt>. Here I've used a bit more
boilerplate code to be able to define most of the rocket structure
preferences without needing separate handlers for them.

=== The OpenRocket format (*.ork) ===

The OpenRocket native format uses the file extension *.ork. It is an XML format, which can optionally be compressed using GZIP. (The extension *.ork.gz is also accepted by the dialogs, though plain .ork is recommended.)

Currently the file format is not documented other than as the reference implementation, and no XML schema exists. This will hopefully change in the future. See [[#Units used in OpenRocket]] for details on units.

Every time the XML format changes, the file version number is increased. This version number is not linked to the version of OpenRocket that created the file, but instead describes the file format. Later versions of OpenRocket should attempt to store files in the oldest format that supports all the necessary features. The changes in the format are described in the [http://openrocket.svn.sourceforge.net/viewvc/openrocket/trunk/fileformat.txt fileformat.txt file in SVN].
''Italic text''