###################
OSVE Python Wrapper
###################

Introduction
============

The OSVE Python Wrapper is a Python package that is just a wrapper of the 
OSVE C++ library and it's responsible of providing a handy object oriented access
to the library's methods from Python scripting.

So the user only needs to import the "osve" package and get an instance
of the "osve" class to start calling available library methods.

The example below just show how to obtain the current OSVE application
version::

    from osve import osve
    sim = osve.osve()
    version = sim.get_app_version()
    print(version)

The user could also obtain current AGM and EPS versions that are already
embed in the OSVE library. For doing this just use the methods:
``get_agm_version()`` or ``get_eps_version()``

But of course the main objective of OSVE is to perform simulations to
obtain the profile of different parameters of interest for mission planning,
or mission analysis.

For running a simulation simply call the method "execute" while passing as
parameters the root path of the simulation and the path to the OSVE session
file in JSON format::


    from osve import osve
    test_input_path = "some path with all the resources inside"
    test_input_config_path = "path to the JSON session file"
    sim = osve.osve()
    sim.execute(test_input_path, test_input_config_path)

OSVE will run the simulation and generate the specified outputs at the 
OSVE JSON session file. A full description of the OSVE session file 
will be done in another section.

In case any error arises the an error message will be reported by OSVE.

The methods ``init_step``, ``execute_step``, ``write_files``, ``write_json_log``
and ``close`` are intended to allow the user to run simulations in a step
by step controlled way. But for the moment this approach has not been 
validated and its use is discouraged. 


Prerequisites
=============
 - Operating Systems: Mac Intel, Mac M1, Linux, and Windows.
 - Python (min v. 3.10)
 - PIP (Python Package Index)


Installation
============
OSVE is available from the Python Package Index repository. Install iy by running the
following command::

    pip install osve

Using the Library
=================

After installing the library can be used with the Python Shell or with its CLI.

Python Shell
------------

A basic test of the library contents can be done as follows::

    from osve import osve
    sim = osve.osve()
    version = sim.get_app_version()
    print(version)

Command line Interface
----------------------

The package has a CLI entry point::

    usage: osve [-h] -r ROOTPATH -s SESSIONFILE

    JUICE Operations Simulation & Validation Engine (OSVE) command line interface
    optional arguments:

    -h, --help            show this help message and exit
    -r ROOTPATH, --RootPath ROOTPATH
                            Top level path of the scenario file_path to be used to resolve the relative paths
    -s SESSIONFILE, --SessionFile SESSIONFILE
                            Location and name of the session file containing all the scenarios files


Usage Examples
--------------

There are a number of JUICE SOC tools that make usage of OSVE. The most remarkable
public ones are listed hereunder:

- `PTWrapper <https://juigitlab.esac.esa.int/python/ptwrapper>`_ Acts as a wrapper to simplify the usage of OSVE to simulate a
  Pointing Timeline and generate the Attitude as a SPICE CK to assist the
  Pointing Timeline Harmonisation of the Detailed Scenario process.
- `juice-phs <https://juigitlab.esac.esa.int/python/juice-phs>`_ Exploits and uses the OSVE capabilities to assist the Instrument
  Timeline Harmonisation of the Detailed Scenario process.


Subscribing to OSVE logs from Python
------------------------------------

OSVE provides support to define your custom Python logging implementations by using callbacks.
In order to define a your custom Python logger, follow this example::

    from osve import osve
    from osve_subscriber import OsveLoggerAbstract

    class OsveLogger(OsveLoggerAbstract):

        def __init__(self):
            super().__init__("theOsveLogger")

        def onMsgReceived(self, severity, module, time, text):
            print("OsveLogger -> " + str(severity) + " , " + str(module) + " , " + str(time) + " , " + str(text))
            return 0


    test_input_path = "SOME_PATH_POINTING_TO_SCENARIO"
    test_input_config_path = "SOME_PATH_POINTING_TO_SESSION_FILE"

    # First, instantiate the OSVE Simulator
    sim = osve.osve()

    # Second, register the logger
    sim.register_logger(OsveLogger())

    # Finally, run simulation
    sim.execute(test_input_path, test_input_config_path)


SPICE Kernels usage
-------------------

.. Warning::
    In order to have an error-free run, OSVE needs to have CK coverage for the
    JUICE S/C reference frame ``JUICE_SPACECRAFT`` (-28000), if this were not the
    case, although OSVE will run logging SPICE Error messages and will generate
    output, the results should be used with care.