.. _juice-spice-readme:
        
=========================================
Using SPICE for JUICE and Jupiter sysmtem
=========================================

Important notes
===============

This document replaces :ref:`pep-spice-readme`.

Kernels
=======

Kernel files are either provided from the project
or obtained from anomymous ftp site,
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels
Some files are personally generated (:ref:`juice_spice_private_kernel`)
As of on 2012-10-23, two files are privately generated (:download:`jse_111130.tf`
and :download:`jeqs_121023_v0.1.tf`.
The preparation of SPICE kernels is the user's responsibility.
The latest JUICE kernels are the one during the proposal AO.

Contact Futaana for kernels needed.

.. _juice_spice_private_kernel:

Private kernels
---------------

In addition to the publically available kernels, private spice kernels are added.
So far, I made two frame definitions (at time time of the version of v0.6beta on 121023).
JSE frame definition (as same definition as GSE) in
:download:`jse_111130.tf` and :download:`jeqs_121023_v0.1.tf`.

In the future, official definition of these frames (or equivalent)
will be provided from mission team.
In such a case, we should remove this functionality from the module.

Definition of private frames
............................

JSE frame is defined similar to GSE frame.

        x-axis
                Sun vector
        y0-axis
                Velocity vector of Jupiter relative to Sun
        z-axis
                Outer product of x and y0
        y-axis
                Outer product of z and x (completing right hand system)

JEqS frame is defined refering to the Jupiter equator.

        z-axis
                North pole (perpendicular to the equator) of Jupiter
        x0-axis
                Sun vector
        y-axis
                Outer product of z and x0
        x-axis
                Outer product of y and z (completing right hand system)


Loading kernels
---------------

Needed kernel files are saved to a local disk.
Multiple files can be loaded via a single MK file,
say :file:`/Volumes/scidata/data/jupiter/kernels/setup1205.mk`

::

  KPL/MK
  \begindata
    PATH_VALUES = ( '/Volumes/scidata/data/jupiter/kernels' )
    PATH_SYMBOLS = ( 'KERNELS' )
    KERNELS_TO_LOAD = (
	  '$KERNELS/1205-kernels/spk/mantra.jgo_2022_ipc_eur_inc_gan_003.bsp'
	  '$KERNELS/1111-kernels/lsk/naif0010.tls'
	  '$KERNELS/1111-kernels/pck/pck00009.tpc'
	  '$KERNELS/1111-kernels/spk/de405.bsp'
	  '$KERNELS/1111-kernels/spk/jup230.bsp'
	  '$KERNELS/1205-kernels/fk/jse_111130.tf'
	  '$KERNELS/1205-kernels/fk/jeqs_121023_v0.1.tf'
    )

To load the MK file, you have to set up .pyanarc file.
This file can be placed in the ${HOME} directory or current directory.

::

  [pep]
  juicemkkernel = /Volumes/scidata/data/jupiter/kernels/setup1205.mk

.. note::

        Entries spicekernels and juice1205kernels are only 
        used from deprecated modules.


Orbit data retrieval
====================

Sample script
-------------

See :mod:`apps120712_spice1205.mission_summary_monthly`.
See :mod:`apps121023_jesframe.xz_moons`.

Tutorial
--------

Import :mod:`pyana.juice.jspice` module and run a function
:func:`pyana.juice.jspice.init`.
All the needed kernels (specified in MK file given in .pyanarc) is
loaded.

.. code-block:: py

        import pyana.juice.jspice
        pyana.juice.jspice.init()

Instead of using those defalut files, you may load
all the needd kernels by hand using :func:`pyana.juice.jspice.furnsh` function.
In this case, you have to connect the name "JGO" to -907 by hand.
It can be done :func:`pyana.juice.jspice.define_jgo` function.
(By historical reason, the JUICE spacecraft name on SPICE is "JGO"
at the time of AO. It will be modified probably later from project.)

.. code-block:: py

        import pyana.juice.jspice
        pyana.juice.jspice.furnsh('./lsk0009.tls')
        ...
        pyana.juice.jspice.define_jgo()


JUICE/Jupiter/moons orbit
-------------------------

Those informations are obtained from :func:`pyana.juice.jspice.get_position`
and :func:`pyana.juice.jspice.get_velocity` functions.

.. code-block:: py

        >>> import datetime
        >>> t= datetime.datetime(datetime.datetime(2031, 6, 5, 12, 55, 15))

        >>> pos = pyana.juice.jspice.get_position(t)
        >>> print '%.2f %.2f %.2f' % (pos[0], pos[1], pos[2])
        97514.29 -1409055.30 550473.59

        >>> vel = pyana.juice.jspice.get_velocity(t)
        >>> print '%.2f %.2f %.2f' % (vel[0], vel[1], vel[2])
        8.98 3.59 2.44

You may also get whatever the objects you like by argument in get_position
(if you have loaded correct kernels).
The default is the "JUICE" position/velocity seen from "JUPITER" in the "JSE" coordinates.
For example, you can get the Io position compread to Jupiter in the "J2000" frame.

.. code-block:: py

        >>> posvel = pyana.juice.jspice.get_posvel(t, target='IO', origin='JUPITER', frame='J2000')
        >>> print posvel
        (419739.997, -51695.912, -17851.201, 2.249, 15.451, 7.387)

Attitude Data
=============

In general, attitude information/calculation can also be handled by the SPICE kernels.
However, there are no instrument kernels or spacecraft kernels.
So that attitude calculations are not yet supported via :mod:`pyana.juice.jspice` module.
You may refer to my implementation of attitude calculation in :ref:`definition_of_frames`.