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

OSVE Use Cases

OSVE currently has the following use cases:

OSVE usage from the command line.
OSVE usage within a Python script or Python Notebook.
OSVE usage through another SOC package, i.e. PTWrapper.
OSVE usage through a web interface, i.e. PORFA, Pointing Tool (via PTWrapper)
OSVE usage through an API, i.e. Pointing Tool API via PTWrapper.

For a direct usage of OSVE, either from the command line or via Python, OSVE requires a complete set of input and configuration files that are usually provided in the JUICE_OPS or JUICE_PREOPS repositories depending on the intended usage along with the necessary SPICE kernels typically from the JUICE SPICE Kernel Dataset provided via BitBucket.

OSVE usage options

In general when OSVE is used both the pointing timeline (AGM) and instrument timeline (EPS) simulations happen. For a pointing timeline simulation the instrument timeline is not really needed (this is the main purpose of the PTWrapper package) however for a complete instrument timeline (or commanding) simulation, the pointing timeline simulation is required in order to obtain the Available Power of the Solar Arrays. This said a pure instrument/commanding timeline can still be run.

OSVE invokes the pointing simulation (AGM) if the attitudeSimulationConfiguration section is present in the session file. i.e.:

"attitudeSimulationConfiguration": {
    "COMMENT: attitudeSimulationConfiguration -> [OPTIONAL] Object intended to define the AGM (AGE) simulation parameters.":"",
  "kernelsList": {
      "COMMENT: kernelsList -> Object intended to define the SPICE Kernels to being used by AGM (AGE) during the simulation.":"",
    "id": "[OPTIONAL][NOT_USED] String with the identifier of the kernel list to be used by AGM (AGE). E.g.: CREMA 3.0",
    "version": "[OPTIONAL][NOT_USED] String with the kernelsList object version, just to have control if any keyword is updated/removed.",
    "baselineRelPath": "[OPTIONAL] String with the relative path to reference all the kernels in the `fileList` array. Default empty string.",
    "fileList": [
        {"COMMENT: fileList -> List of SPICE Kernels to being used by AGM (AGE) during the simulation.":""},
      {
        "fileRelPath": "String with the relative path of a SPICE kernel to load. Can be specified multiple times.",
        "description": "[OPTIONAL] String with the description of the SPICE kernel to load."
      }
    ]
  }

Similarly, OSVE invokes the instrument timeline/commanding simulation (EPS) if the instrumentSimulationConfiguration section is present in the session file. i.e.:

"instrumentSimulationConfiguration": {
    "COMMENT: instrumentSimulationConfiguration -> [OPTIONAL] Object intended to define the ISE (EPS) simulation parameters.":"",
  "baselineRelPath": "[OPTIONAL] String with the relative path to reference all the EPS configuration files. Default empty string.",
  "unitFileName": "String with the relative path of the EPS Units definition file.",
  "configFileName": "String with the relative path of the EPS configuration file.",
  "eventDefFileName": "String with the relative path of the EPS event definitions file."
},

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.subscribers.osve_logger_abstract 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.