Positional Path (Python)

Description

Allows defining a platform's positional trajectory using a user-provided external Python function, specified within the <motionpath> XML element using the <pythonpath module="..." function="..."> tag. Instead of using pre-defined waypoints and interpolation methods, FERS will call this specified Python function at different simulation times t to dynamically determine the platform's (x, y, z) coordinates in the simulation's Cartesian frame.

Assumptions

• Assumes the Python module file (.py) exists and is accessible within Python's search path (FERS adds the execution directory to the path).
• Assumes the specified module contains the specified function.
• Assumes the Python function accepts exactly one argument, the simulation time t (passed as a floating-point number, RealType).
• Assumes the Python function returns a sequence (specifically checked for a Python Tuple) containing exactly three numeric values convertible to double (representing x, y, z coordinates).
• Assumes the logic implemented within the Python script correctly calculates the desired trajectory according to the simulation's coordinate system and time units (typically meters and seconds).
• Assumes the necessary Python environment (a compatible Python version, typically 3.7-3.11 as checked by FERS) is correctly installed and configured on the system running FERS.
• Assumes the underlying Python C API calls used by FERS to interact with the interpreter succeed without internal errors.

Limitations

• Performance: Execution speed depends heavily on the complexity of the Python script and the overhead of the C++/Python interface calls (including data marshalling and the Global Interpreter Lock). This method can be significantly slower than native C++ waypoint interpolation methods, especially if the position is requested very frequently during the simulation.
• Multipath Incompatibility: Platforms using Python-defined positional paths cannot have their paths reflected for multipath simulation. The reflectPath function explicitly checks for this type (INTERP_PYTHON) and will throw an error, preventing simulation setup.
• Debugging Complexity: Debugging errors or logical issues within the external Python script is generally more complex and less integrated than debugging internal FERS C++ logic. Standard C++ debuggers cannot step directly into the Python code.
• Error Handling: Errors occurring during the execution of the Python function (e.g., Python exceptions, incorrect return type/size, module/function not found) will typically result in C++ std::runtime_error exceptions being thrown within FERS, potentially halting the simulation abruptly. Error messages might originate from the Python interpreter (PyErr_Print) directed to standard error, offering less context within FERS logs.
• External Dependency: The accuracy and robustness of the trajectory calculation rely entirely on the user-provided external Python code. FERS performs minimal validation beyond checking the return type and size.

Related Components

• XML Element: <motionpath> with child <pythonpath module="..." function="...">
• C++ Class: Path (in path.h, manages different interpolation types, stores _pythonpath)
• C++ Class: PythonPath (in python_path.h/.cpp, handles the Python C API interaction, function calls, and return value conversion)
• Parsing Logic: xml_parser.cpp (function parseMotionPath handles the <pythonpath> tag)
• Core Logic: Path::getPosition method (in path.cpp, calls PythonPath::getPosition when _type is INTERP_PYTHON)
• Internal API: Python C API (used within PythonPath class)

Validation Status

• Needs Verification: The core mechanism of dynamically calling a user-defined Python function at various simulation times and correctly interpreting the returned 3-tuple (x, y, z) coordinates needs robust verification. The error handling pathways for various Python script failure modes (e.g., exceptions, wrong return types, slow execution, missing modules/functions) require specific testing.
• Key Areas for Validation:
  • Correctness of coordinate data transfer: time t passed accurately to Python, and the returned (x, y, z) tuple correctly converted back to a FERS Vec3.
  • Handling of different numeric types (int, float) returned within the Python tuple.
  • Performance impact assessment compared to native waypoint methods for representative trajectory complexities and sampling rates.
  • Behavior when the Python environment is misconfigured (e.g., wrong version, missing libraries implicitly needed by the user script).
  • Behavior when the specified module or function cannot be found or loaded by Python.
  • Correct propagation of Python exceptions into catchable C++ exceptions (std::runtime_error).
  • Verification that attempting to use Python paths with multipath surface definitions correctly triggers the documented error during setup (reflectPath check).
• Priority: High (Due to external dependency, potential performance issues, and complexity of interaction)