[Docs] Missing examples for direct Python-ML coupling (PyTorch/TensorFlow)

[ayush4874]

Problem Description

The current Python Wrapper examples primarily focus on shape optimization (FADO) or basic fluid driver execution. However, with the growing interest in Physics-Informed Machine Learning (PIML) and the integration of MLPCpp, there are no clear examples demonstrating how to couple the SU2 solver with external ML libraries (like PyTorch) in a single process.

Users currently have to guess how to extract field variables (e.g., RMS_DENSITY) from memory and pass them to a training loop in real-time.

Proposed Solution

I propose adding a dedicated example directory SU2_PY/examples/hybrid_ml_coupling/ containing a script that demonstrates:

1. Initializing the CSinglezoneDriver with mpi4py.
2. Running a time-stepping loop where the solver runs alongside a lightweight surrogate model.
3. Extracting flow data from memory (using GetOutputValue) to train the model online.

I have prototyped a working script using PyTorch and would like to submit a PR to add this to the documentation/examples.

[ayush4874]

I have migrated the example code to the Tutorials repository as requested by @bigfooted.

The new PR is here: su2code/Tutorials#71

I will leave this issue open until that PR is merged to track the resolution.

[ayush4874]

Update: I have also submitted the corresponding documentation page as requested.

Documentation PR: su2code/su2code.github.io#189

[pcarruscag]

@EvertBunschoten you are the resident ML expert, please review these PRs

[ayush4874]

Hi @EvertBunschoten, thanks for taking a look!

While working on the documentation, I've also been digging into MLPCpp/include/CLookUp_ANN.hpp to architect the next step (Dynamic Weight Injection).

It seems NeuralNetworks is strictly private and GenerateANN only supports file-based I/O. This effectively locks the model to "Read-Only" status after initialization.

I have prototyped a patch locally that breaks this encapsulation (adding a SetWeights interface), and I successfully updated the network parameters mid-simulation from the Python driver.

I plan to formalize this refactoring for my GSoC 2026 proposal. Before I do:
Does the team have concerns about thread safety when updating these weights during an MPI run?
(My current prototype assumes the Python driver handles the synchronization before pushing the weights, but I'd like to align with the core philosophy).