Python Motion Interpolation

Description

This feature allows a platform's positional trajectory to be defined by an external, user-provided Python function. FERS calls this function at specific times during the simulation, expecting it to return the platform's Cartesian coordinates (x, y, z) at that instant. The specific Python module and function are specified in the FERS configuration (e.g., via the <pythonpath> tag in XML).

Assumptions

• Assumes the Python module file specified in the configuration exists and is accessible in the Python environment's path (including the current execution directory).
• Assumes the specified Python module contains a function with the exact name provided in the configuration.
• Assumes the Python function accepts exactly one argument, representing the simulation time t (expected as a float).
• Assumes the Python function returns a sequence (specifically, FERS checks for a PyTuple) containing exactly three numeric values (convertible to C++ double) representing the platform's position (x, y, z).
• Assumes the time and position units used within the Python function are consistent with FERS' internal units (typically seconds for time and meters for position coordinates).

Limitations

• Position Only: The Python function directly provides only the platform's position (Vec3). It does not define rotation/orientation, velocity, or acceleration. These must be handled separately (e.g., using a separate rotational path definition) or derived indirectly if needed (e.g., by calculating velocity from multiple getPosition calls, which may be inaccurate).
• Performance Overhead: Each call to the Python function from C++ incurs performance overhead associated with the Python interpreter, including data type conversions between C++ and Python, the Python function call itself, and potential contention on Python's Global Interpreter Lock (GIL). This can be significantly slower than using native C++ waypoint interpolation methods, especially if the function is called very frequently (e.g., for high cwSampleRate or many simulation steps).
• Limited Data Interface: Only the current simulation time (t) is passed as an argument to the Python function. There is no built-in mechanism to pass other simulation state information (e.g., platform ID, status of other objects) into the Python function.
• Basic Error Handling: If the Python module/function cannot be loaded, if the function signature is incorrect (wrong number of arguments), if the return type is not a 3-element tuple, or if the Python function itself raises an exception during execution, FERS typically catches this and throws a generic C++ std::runtime_error. Debugging the root cause within the Python script may require external tools or logging within the Python code itself.

Related Components

• C++ Interface Class: python::PythonPath (defined in python_extension.h)
• C++ Call Logic: Primarily within python::PythonPath::getPosition(RealType t) (implemented in python_extension.cpp)
• Expected Python Function Signature: def function_name(time: float) -> tuple[float, float, float]: ...
• Configuration: Defined via <pythonpath> tag within a <platform> element in the XML scenario file.
• Python Integration (Category Page)
• Platform Motion (Category Page)

Validation Status

• Needs Verification: The robustness, performance, and accuracy of this feature under various conditions require specific validation tests.
• Key Areas for Validation:
  • Correct passing of simulation time (t) to the Python function.
  • Accurate conversion of the returned Python tuple (x, y, z) to a C++ Vec3.
  • Handling of different valid numeric types within the returned Python tuple (e.g., int, float).
  • Robustness and error reporting when the Python module or function is missing or incorrectly named.
  • Robustness and error reporting when the Python function has an incorrect signature (wrong number of arguments).
  • Robustness and error reporting when the Python function returns an incorrect type (not a tuple) or size (not 3 elements).
  • Correct propagation of exceptions raised within the Python function back to C++.
  • Performance benchmarking against native C++ interpolation methods for representative scenarios.
  • Verification of unit consistency (time in seconds, position in meters) between C++ and Python.
• Priority: Medium (Core functionality impacting platform position, but relies on external user code and may have performance implications).