From c01d66a41da8f82c94666eee865b625bfb9ee9ae Mon Sep 17 00:00:00 2001
From: petrush <petrus.hyvonen@sscspace.com>
Date: Sun, 1 Mar 2020 20:41:40 +0100
Subject: [PATCH] More basic documentation

---
 examples/The_Basics.ipynb | 122 ++++++++++++++++++++++++++++++++++----
 1 file changed, 110 insertions(+), 12 deletions(-)

diff --git a/examples/The_Basics.ipynb b/examples/The_Basics.ipynb
index add33c8..f97ff03 100644
--- a/examples/The_Basics.ipynb
+++ b/examples/The_Basics.ipynb
@@ -34,16 +34,43 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The orekit library is written and executing in java. However for interactive work a bridge to Python has been made, the \"orekit python wrapper\" which will be used in this tutorial."
+    "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",
    "metadata": {},
    "source": [
-    "The orekit java library has been wrapped using the open source JCC tool, that enables interaction with java objects from the Python ecosystem.\n",
+    "## Architecture "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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. \n",
+    "\n",
+    "![Architecture Diagram](images/Architecture.JPG)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following parts are wrapped:\n",
+    "  - The [Orekit](https://www.orekit.org/) astrodynamics library is explitly wrapped\n",
+    "  - The [Rugged](https://www.orekit.org/rugged/) a sensor to terrain mapping library is also explicitly wrapped\n",
+    "  - The needed [Hipparchus](https://www.hipparchus.org/) mathematics libary is explicitly wrapped\n",
+    "  - Some selected classes from the java tree is also wrapped, classes that are needed for methods or class initialization\n",
     "\n",
-    "<embed src=\"files/images/integration.svg\" type=\"image/svg+xml\" />"
+    "A module with some helper files, orekit.pyhelpers, is included for some convertions etc."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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."
    ]
   },
   {
@@ -122,6 +149,27 @@
     "# download_orekit_data_curdir()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setting the Envionment parameters"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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:\n",
+    "  - Starting the jupyter notebook, IDE or other through the Anaconda launcher\n",
+    "  - Using the conda-wrappers tool to get the environment automatically activated when accessing python.bat\n",
+    "  - Manually starting the python from the Anaconda command prompt\n",
+    "  - Hardcoding the JCC_JDK and PATH (on windows) environment parameters in your computer setup\n",
+    "  ...\n",
+    "  \n",
+    "Please see the [wiki](https://gitlab.orekit.org/orekit-labs/python-wrapper/-/wikis/installation) for more details "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -270,14 +318,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For many users there will be no or little differnce in the usage of Orekit between Java and Python. The following chapter provides additional information for more advanced usage."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "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.\n"
+    "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. \n",
+    "\n",
+    "The following chapter provides additional information for more advanced usage. "
    ]
   },
   {
@@ -370,7 +413,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In some use cases it is relevant to subclass a java class for an own implementation. For the standard orekit classes this is not possible, but a work-around has been implemented for selected classes that allows Python subclassing. These classes are labeled as their corresponding java classes but with a \"Python\" prefix."
+    "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.\n",
+    "\n",
+    "*It should be noted that all PythonClasses that don't have a test case shall be considered experimental*"
    ]
   },
   {
@@ -408,6 +453,59 @@
    "outputs": [],
    "source": []
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Overloaded Methods / Constructors "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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",
+   "metadata": {},
+   "source": [
+    "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:\n",
+    "  - The most \"obvious\" (!) usage will have the default Java name, same as in Orekit\n",
+    "  - 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.\n",
+    "  \n",
+    "Example:\n",
+    "\n",
+    "   PythonExtendedPVCoordinatesProvider.getPVCoordinates(AbsoluteDate date, Frame frame)\n",
+    "   PythonExtendedPVCoordinatesProvider.getPVCoordinates_FF(FieldAbsoluteDate<T> date, Frame frame)\n",
+    "    \n",
+    "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",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Performance"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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.\n",
+    "\n",
+    "Frequent callbacks to Python from Java should be avoided for other purposes than prototyping."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
-- 
GitLab