Updated documentation on python subclassing and __init__

Updated documentation on python subclassing and init
38e13071 · Petrus Hyvönen · 6ac2963e · 38e13071
Commit 38e13071 authored 4 years ago by Petrus Hyvönen
--- a/examples/The_Basics.ipynb
+++ b/examples/The_Basics.ipynb
@@ -144,7 +144,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
@@ -204,7 +204,7 @@
     "output_type": "stream",
     "text": [
      "Java version: 1.8.0_152-release\n",
-      "Orekit version: 10.0\n"
+      "Orekit version: 10.2\n"
     ]
    }
   ],
@@ -243,7 +243,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
@@ -252,7 +252,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
@@ -351,7 +351,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
@@ -360,7 +360,7 @@
       "<Vector3D: {138,869,605,874.96655; -47,461,924,824.28846; -20,575,480,674.707344}>"
      ]
     },
-     "execution_count": 20,
+     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
@@ -430,6 +430,52 @@
    "Example:"
   ]
  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from org.orekit.propagation.sampling import PythonOrekitFixedStepHandler"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class StepHandler(PythonOrekitFixedStepHandler):\n",
+    "    \n",
+    "    def __init__(self, my_value):\n",
+    "        self.my_value = my_value\n",
+    "        super(StepHandler, self).__init__()\n",
+    "\n",
+    "    def init(self, s0, t, step):\n",
+    "        pass\n",
+    "\n",
+    "    def handleStep(self, state, isLast):\n",
+    "        # your code goes here that is executed for every step\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the example above, note:\n",
+    "\n",
+    "  - The class is subclassing a special class, instead of OrekitFixedStepHandler, PythonOrekitFixedStepHandler is used.\n",
+    "  - All methods in the class / interface needs to be implemented for java to accept it. If not used, just use a pass statement.\n",
+    "  - If a custom __init__ is used, the super needs also to be called to finalize the initialization of the object"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
  {
   "cell_type": "markdown",
   "metadata": {},
@@ -586,7 +632,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {

 %% Cell type:markdown id: tags:
 # Orekit in Python - The Basics
 %% Cell type:markdown id: tags:
 Orekit is an open-source library for astrodynamical calculations such as:
 * Orbit Propagation
 * Coordinate system transformations
 * Time systems
 * Orbit Determination
 And much more..
 The orekit webpage can be accessed at http://www.orekit.org.
 %% Cell type:markdown id: tags:
 ## The Java - Python bridge - "orekit python wrapper"
 %% Cell type:markdown id: tags:
 The orekit library is written and executing in java. However for interactive there are some advantages using the Python scientific ecosystem, that gives access to a variety of packages ranging from science to visualization and mapping. With the introduction of Jupyter notebooks, this has been highlighted further when a document based approach can be used, in a simple browser interface.
 %% Cell type:markdown id: tags:
 ## Architecture
 %% Cell type:markdown id: tags:
 The architecture of the Orekit Python Wrapper is centered around the open-source tool JCC. This tool analyzes the java library and creates C++ classes that wraps each Orekit Java class and interfaces these using JNI. Then Pyton classes are generated for accessing the C++ classes.
 ![Architecture Diagram](images/Architecture.JPG)
 %% Cell type:markdown id: tags:
 The following parts are wrapped:
  - The [Orekit](https://www.orekit.org/) astrodynamics library is explitly wrapped
  - The [Rugged](https://www.orekit.org/rugged/) a sensor to terrain mapping library is also explicitly wrapped
  - The needed [Hipparchus](https://www.hipparchus.org/) mathematics libary is explicitly wrapped
  - Some selected classes from the java tree is also wrapped, classes that are needed for methods or class initialization
 A module with some helper files, orekit.pyhelpers, is included for some convertions etc.
 %% Cell type:markdown id: tags:
 The Python version, or correctly stated the Python Wrapper (it is a pure java orekit that runs in background) has a few areas where there are specific ways to do things, limitations and some quirks. The wrapper is created with a tool called JCC (https://lucene.apache.org/pylucene/jcc/), which is providing most of these features and the documentation for that is relevant.
 %% Cell type:markdown id: tags:
 # Installation
 %% Cell type:markdown id: tags:
 ### Install Anaconda
 %% Cell type:markdown id: tags:
 The recommended way to install the orekit python wrapper is through the pre-built packages for the Anaconda python distribution.
 The Anaconda python distribution can be downloaded at:
 https://www.anaconda.com/distribution/
 %% Cell type:markdown id: tags:
 ### Install Orekit Python Wrapper Conda package
 %% Cell type:markdown id: tags:
 A pre-built orekit package for conda is created in the conda-forge channel, and can be installed in the conda environment by:
    conda install orekit -c conda-forge
 This should download and install the orekit package into the currently activated conda environment, and install the dependenies (openjdk).
 For some usages it is useful to install conda-wrappers, for example if using an IDE like PyCharm. The conda-wrappers are installed in the same way:
    conda install conda-wrappers -c conda-forge
 %% Cell type:markdown id: tags:
 ### Getting the orekit-data.zip file
 %% Cell type:markdown id: tags:
 Some fundamental parameters are not included in the orekit package, and should be provided separately. Such files are earth orientation parameters, time standards etc. An example collection of such parameters are available on the orekit page (no guaratees, this data should be maintained by the user for any professional usage).
 The datafile is default accessed in current orekit directory or a path can be supplied. The file can be downloaded from https://gitlab.orekit.org/orekit/orekit-data
 A convenience function to download this file is included in the orekit package.
 %% Cell type:code id: tags:
 ``` python
 from orekit.pyhelpers import download_orekit_data_curdir
 # download_orekit_data_curdir()
 ```
 %% Cell type:markdown id: tags:
 ## Setting the Envionment parameters
 %% Cell type:markdown id: tags:
 The Orekit wrapper needs a few environment variables to be set. This is automatically done in the conda package when the environment is activated. But it needs to be activated. This can be done through various ways:
  - Starting the jupyter notebook, IDE or other through the Anaconda launcher
  - Using the conda-wrappers tool to get the environment automatically activated when accessing python.bat
  - Manually starting the python from the Anaconda command prompt
  - Hardcoding the JCC_JDK and PATH (on windows) environment parameters in your computer setup
  ...
 Please see the [wiki](https://gitlab.orekit.org/orekit-labs/python-wrapper/-/wikis/installation) for more details
 %% Cell type:markdown id: tags:
 # Initiating Orekit in Python
 %% Cell type:markdown id: tags:
 Orekit needs to be initiated before used, this starts up the java engine and exposes the orekit classes in python.
 %% Cell type:markdown id: tags:
 To start up orekit use the initVM() function:
 %% Cell type:code id: tags:
 ``` python
 import orekit
 vm = orekit.initVM()
 print ('Java version:',vm.java_version)
 print ('Orekit version:', orekit.VERSION)
 ```
 %% Output
    Java version: 1.8.0_152-release
-    Orekit version: 10.0
+    Orekit version: 10.2
 %% Cell type:markdown id: tags:
 The orekit library needs a data file with various information on time and earth rotation parameters. This file, called orekit-data.zip is loaded from current dir as default.
 This routine of setting up these parameters is commonly used in the notebooks, so a python specific function is created for this, setup_orekit_curdir()
 %% Cell type:code id: tags:
 ``` python
 from orekit.pyhelpers import setup_orekit_curdir
 setup_orekit_curdir()
 ```
 %% Cell type:markdown id: tags:
 Now we are set up to import and use objects from the orekit library. With the proper initialization, all objects in the orekit java library is exposed to Python and can be imported using normal Python syntax.
 %% Cell type:code id: tags:
 ``` python
 from org.orekit.utils import Constants
 ```
 %% Cell type:code id: tags:
 ``` python
 print (Constants.WGS84_EARTH_EQUATORIAL_RADIUS)
 ```
 %% Output
    6378137.0
 %% Cell type:markdown id: tags:
 SI base units are used in the library, such as seconds, meter, m/s
 %% Cell type:markdown id: tags:
 # Documentation
 %% Cell type:markdown id: tags:
 One of the best sources of knowledge about orekit and the Python wrapper is on the orekit forum, https://forum.orekit.org/
 %% Cell type:markdown id: tags:
 ## Orekit API
 %% Cell type:markdown id: tags:
 The Python version of orekit is very closely matching the java version and the API documentation from Java can be used. This documentation is available at https://www.orekit.org/site-orekit-10.1/apidocs/index.html
 %% Cell type:markdown id: tags:
 In addition to the API documentation there are a number of architecture descriptions, based on the Java syntax but highly applicable to the Python side. See https://www.orekit.org/doc-maven.html
 %% Cell type:markdown id: tags:
 # Specifics for the Python version of Orekit
 %% Cell type:markdown id: tags:
 For many users there will be no or little differnce in the usage of Orekit between Java and Python. At basic level it seems to be almost identical usage and most code can be translated almost mechanically.
 The following chapter provides additional information for more advanced usage.
 %% Cell type:markdown id: tags:
 ## Casting of classes
 %% Cell type:markdown id: tags:
 Java is a more strongly typed language than Python and is indirectly casting classes as part of the syntax. In most cases the Python user does not need to consider this when using orekit in Python, but in some cases it may be neccessary to specify which type or interface of a particular object that is refered to.
 %% Cell type:markdown id: tags:
 Example:
 %% Cell type:code id: tags:
 ``` python
 from org.orekit.bodies import CelestialBodyFactory
 from org.orekit.utils import PVCoordinatesProvider
 from org.orekit.time import AbsoluteDate, TimeScalesFactory
 from org.orekit.frames import FramesFactory
 sun = CelestialBodyFactory.getSun()     # Here we get it as an CelestialBody
 sun = PVCoordinatesProvider.cast_(sun)  # But we want the PVCoord interface
 # Get the position of the sun in the Earth centered coordinate system EME2000
 date = AbsoluteDate(2020, 2, 28, 23, 30, 0.0, TimeScalesFactory.getUTC())
 sun.getPVCoordinates(date, FramesFactory.getEME2000()).getPosition()
 ```
 %% Output
    <Vector3D: {138,869,605,874.96655; -47,461,924,824.28846; -20,575,480,674.707344}>
 %% Cell type:markdown id: tags:
 ## Usage of parametric types
 %% Cell type:markdown id: tags:
 The Java language has a feature of parametric class definitions and orekit uses this in some areas. These can be managed in Python with the _of(Class) method that sets this.
 %% Cell type:markdown id: tags:
 Example:
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:markdown id: tags:
 ## Subclassing Java classes in Python
 %% Cell type:markdown id: tags:
 In some use cases it is relevant to subclass a java class for an own implementation. Subclassing of Java classes in Python is possible but some adjustments in Java are needed to the classes that are to be subclassed. Instead of modifying the original orekit classes, specific "PythonClassName" classes have been created for interfaces and selected classes.
 *It should be noted that all PythonClasses that don't have a test case shall be considered experimental*
 %% Cell type:markdown id: tags:
 Example:
+%% Cell type:code id: tags:
+``` python
+from org.orekit.propagation.sampling import PythonOrekitFixedStepHandler
+```
+%% Cell type:code id: tags:
+``` python
+class StepHandler(PythonOrekitFixedStepHandler):
+    def __init__(self, my_value):
+        self.my_value = my_value
+        super(StepHandler, self).__init__()
+    def init(self, s0, t, step):
+        pass
+    def handleStep(self, state, isLast):
+        # your code goes here that is executed for every step
+```
+%% Cell type:markdown id: tags:
+In the example above, note:
+  - The class is subclassing a special class, instead of OrekitFixedStepHandler, PythonOrekitFixedStepHandler is used.
+  - All methods in the class / interface needs to be implemented for java to accept it. If not used, just use a pass statement.
+  - If a custom __init__ is used, the super needs also to be called to finalize the initialization of the object
+%% Cell type:code id: tags:
+``` python
+```
 %% Cell type:markdown id: tags:
 ## Implementation of Java Interfaces in Python
 %% Cell type:markdown id: tags:
 The implementation of orekit interfaces in Python is performed in the same way as subclassing, where all interfaces has a corresponding "Python" prefixed version that can be subclassed in python in order to implement that interface.
 %% Cell type:markdown id: tags:
 Example:
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:markdown id: tags:
 Note: It is not possible to implement several interfaces to a Python class
 %% Cell type:markdown id: tags:
 ## init or \_\_init\_\_ in subclassing
 %% Cell type:markdown id: tags:
 The Python function for initializing a class is typically the \_\_init\_\_(self, ...) method. Several Orekit interfaces and abstract classes have a init() method that is used for similar purposes. In many Interfaces and Abstract classes, the init(...) method needs to be there for it to be an accepted implementation. For the purpose of populating the interface, it is enough in Python to specify an empty method:
 %% Cell type:code id: tags:
 ``` python
 def init(self):
    pass
 ```
 %% Cell type:markdown id: tags:
 In most practical cases when the class is initialized upon creation, it is suitable to use the more Pythonic \_\_init\_\_ method instead.
 %% Cell type:markdown id: tags:
 ## Overloaded Methods / Constructors
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:markdown id: tags:
 Python does not have overloaded methods / constructors as in Java. For calls this is not a problem as the Java side will try to figure out which method / constructor to use. However, when subclassing Java classes in Python that has overloaded methods or constructors, special care is needed.
 %% Cell type:markdown id: tags:
 For these classes and interfaces where Orekit uses overloaded methods (methods with same name but different parameters) a workaround has been done. The following rules has been applied and a set of differently named methods or constructors has been included:
  - The most "obvious" (!) usage will have the default Java name, same as in Orekit
  - Other methods (often Field varieties) will have an extension to the method name consistinf of the first letter(s) of the types of the input parameters.
 Example:
   PythonExtendedPVCoordinatesProvider.getPVCoordinates(AbsoluteDate date, Frame frame)
   PythonExtendedPVCoordinatesProvider.getPVCoordinates_FF(FieldAbsoluteDate<T> date, Frame frame)
 Note that it is *only* needed to use this when subclassing, otherwise one can use the normal calls as in the Java API.
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:markdown id: tags:
 ## Performance
 %% Cell type:markdown id: tags:
 The performance of Python Orekit has not been properly measured compared to a pure Java implementation, but there are performance penalties in the interchange between Python and Java. This interaction reduces the possibility of end-to-end Just-In-Time optimizations. But the effect depends a lot on how it is used, a propagation that is fully performed in the Java side and only configured from the Python side will have a minimal impact - the "internal" performance of Orekit is not affected.
 Frequent callbacks to Python from Java should be avoided for other purposes than prototyping.
 %% Cell type:markdown id: tags:
 ## Pythonic methods
 %% Cell type:markdown id: tags:
 Orekit is built with the JCC options to translate Java getters and setters to more "Pythonic" class variables. This is performed by detecting .getMethod and .setMethod to simply a .method on the class. Note the change of case as well of first variable. It can be discussed how recommended this is as it provides an addition to the original orekit API. But it can be argued that it does increase readability.
 %% Cell type:markdown id: tags:
 Example:
 %% Cell type:code id: tags:
 ``` python
 from org.hipparchus.geometry.euclidean.threed import Vector3D
 a = Vector3D(2.0, 0.0, 0.0)
 print(a.getX(), a.getY(), a.getZ())
 print(a.x, a.y, a.z)
 ```
 %% Output
    2.0 0.0 0.0
    2.0 0.0 0.0
 %% Cell type:markdown id: tags:
 ## Variable number of arguments functions
 %% Cell type:markdown id: tags:
 Java and Orekit are for some methods using a variable number of inputs, identified as ... in the API. For example the:
    BooleanDetector.andCombine(EventDetector... detectors)
 method in Java. To use this in Python, the variable arguments are placed in a list [], like:
    BooleanDetector.andCombine([illumination_detector, el_detector])
 %% Cell type:code id: tags:
 ``` python
 ```
 %% Cell type:markdown id: tags:
 *Petrus Hyvönen, 2020*