Started on better intro

examples/The_Basics.ipynb

@@ -4,42 +4,44 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Orekit in Python - The basics"
+    "# Orekit in Python - The Basics"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Orekit is an open-source library for a number of space related calculations such as:\n",
+    "Orekit is an open-source library for astrodynamical calculations such as:\n",
     "\n",
     "* Orbit Propagation\n",
     "* Coordinate system transformations\n",
     "* Time systems\n",
+    "* Orbit Determination\n",
     "\n",
-    "The orekit webpage can be accessed at http://www.orekit.org.\n",
-    "\n"
+    "And much more..\n",
+    "\n",
+    "The orekit webpage can be accessed at http://www.orekit.org.\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## The java - pyhon bridge"
+    "## The Java - Python bridge - \"orekit python wrapper\""
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The orekit library is written in java. For interactive work a bridge to Python has been made, which will be used in this tutorial."
+    "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."
    ]
   },
   {
    "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. Python has quick and high quality routines for plotting and a easily read code.\n",
+    "The orekit java library has been wrapped using the open source JCC tool, that enables interaction with java objects from the Python ecosystem.\n",
     "\n",
     "<embed src=\"files/images/integration.svg\" type=\"image/svg+xml\" />"
    ]
@@ -48,79 +50,132 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Initiating orekit in python"
+    "# Installation "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install Anaconda"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The recommended way to install the orekit python wrapper is through the pre-built packages for the Anaconda python distribution. \n",
+    "\n",
+    "The Anaconda python distribution can be downloaded at:\n",
+    "https://www.anaconda.com/distribution/\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install Orekit Python Wrapper Conda package"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A pre-built orekit package for conda is created in the conda-forge channel, and can be installed in the conda environment by:\n",
+    "\n",
+    "    conda install orekit -c conda-forge\n",
+    "   \n",
+    "This should download and install the orekit package into the currently activated conda environment, and install the dependenies (openjdk).\n",
+    "\n",
+    "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:\n",
+    "\n",
+    "    conda install conda-wrappers -c conda-forge\n",
+    "    \n",
+    " "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Orekit needs to be initiated before used, partly setting up the Python - both the Java gateway and partly setting up access to the data needed for different orekit functions, such as the shape of the earth, leap time seconds etc."
+    "### Getting the orekit-data.zip file "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "First we need to intitilize the iPython notebook, that we want to use the inline pylab functionality and how large defalt plots should be. This is not orekit specific."
+    "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).\n",
+    "\n",
+    "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\n",
+    "\n",
+    "A convenience function to download this file is included in the orekit package."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 2,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Populating the interactive namespace from numpy and matplotlib\n"
-     ]
-    }
-   ],
+   "outputs": [],
+   "source": [
+    "from orekit.pyhelpers import download_orekit_data_curdir\n",
+    "# download_orekit_data_curdir()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Initiating Orekit in Python"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    "%pylab inline\n",
-    "figsize(15,15)"
+    "Orekit needs to be initiated before used, this starts up the java engine and exposes the orekit classes in python."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To start up the orekit JVM:"
+    "To start up orekit use the initVM() function:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Java version: 1.8.0_92\n"
+      "Java version: 1.8.0_152-release\n",
+      "Orekit version: 10.0\n"
      ]
     }
    ],
    "source": [
     "import orekit\n",
     "vm = orekit.initVM()\n",
-    "print ('Java version:',vm.java_version)"
+    "print ('Java version:',vm.java_version)\n",
+    "print ('Orekit version:', orekit.VERSION)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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. A basic version of this file can be downloaded from the orekit  [webpage](https://www.orekit.org/forge/projects/orekit/files).\n",
+    "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. \n",
     "\n",
-    "This routine is commonly used in the notebooks, so a python specific function is created for this, setup_orekit_curdir()"
+    "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",
-   "execution_count": 4,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -132,12 +187,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we are set up to import and use objects from the orekit library."
+    "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",
-   "execution_count": 5,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -146,7 +201,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [
     {
@@ -172,14 +227,213 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "*Petrus Hyvönen, SSC, 2014*"
+    "# Documentation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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",
+   "metadata": {},
+   "source": [
+    "## Orekit API "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Specifics for the Python version of Orekit"
+   ]
+  },
+  {
+   "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"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Casting of classes "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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",
+   "metadata": {},
+   "source": [
+    "Example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Vector3D: {138,869,605,874.96655; -47,461,924,824.28846; -20,575,480,674.707344}>"
+      ]
+     },
+     "execution_count": 20,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from org.orekit.bodies import CelestialBodyFactory\n",
+    "from org.orekit.utils import PVCoordinatesProvider\n",
+    "from org.orekit.time import AbsoluteDate, TimeScalesFactory\n",
+    "from org.orekit.frames import FramesFactory\n",
+    "\n",
+    "sun = CelestialBodyFactory.getSun()     # Here we get it as an CelestialBody\n",
+    "sun = PVCoordinatesProvider.cast_(sun)  # But we want the PVCoord interface\n",
+    "\n",
+    "# Get the position of the sun in the Earth centered coordinate system EME2000\n",
+    "date = AbsoluteDate(2020, 2, 28, 23, 30, 0.0, TimeScalesFactory.getUTC())\n",
+    "sun.getPVCoordinates(date, FramesFactory.getEME2000()).getPosition()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Usage of parametric types"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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",
+   "metadata": {},
+   "source": [
+    "Example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Subclassing Java classes in Python "
+   ]
+  },
+  {
+   "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."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Example:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Implementation of Java Interfaces in Python "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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",
+   "metadata": {},
+   "source": [
+    "Example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: It is not possible to implement several interfaces to a Python class"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "*Petrus Hyvönen, SSC, 2020*"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "hide_input": false,
   "kernelspec": {
-   "display_name": "Python [default]",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -193,7 +447,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.3"
+   "version": "3.7.6"
   },
   "toc": {
    "base_numbering": 1,
@@ -214,5 +468,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }