From 3b1bf93dcd4f3a7897da8e0a980a59f25e6f7a37 Mon Sep 17 00:00:00 2001
From: Kishan_Singh <147229665+kishansinghifs1@users.noreply.github.com>
Date: Mon, 23 Feb 2026 17:07:53 +0000
Subject: [PATCH] Add Python callback interface tutorial and related scripts
 for elastic tube case

---
 elastic-tube-1d/README.md                     | 55 +++++++++++++
 .../fluid-python/FluidSolverCallback.py       | 22 ++++++
 elastic-tube-1d/fluid-python/run-callback.sh  | 16 ++++
 elastic-tube-1d/precice-config-callback.xml   | 78 +++++++++++++++++++
 .../solid-python/SolidSolverCallback.py       | 22 ++++++
 .../solid-python/pressureRampAction.py        |  7 ++
 elastic-tube-1d/solid-python/run-callback.sh  | 16 ++++
 7 files changed, 216 insertions(+)
 create mode 100644 elastic-tube-1d/fluid-python/FluidSolverCallback.py
 create mode 100644 elastic-tube-1d/fluid-python/run-callback.sh
 create mode 100644 elastic-tube-1d/precice-config-callback.xml
 create mode 100644 elastic-tube-1d/solid-python/SolidSolverCallback.py
 create mode 100644 elastic-tube-1d/solid-python/pressureRampAction.py
 create mode 100644 elastic-tube-1d/solid-python/run-callback.sh

diff --git a/elastic-tube-1d/README.md b/elastic-tube-1d/README.md
index a3552f271..6a2d8191a 100644
--- a/elastic-tube-1d/README.md
+++ b/elastic-tube-1d/README.md
@@ -43,6 +43,61 @@ Both fluid and solid participant are supported in:
 - *Python*: example solvers using the preCICE [Python bindings](https://precice.org/installation-bindings-python.html). The run script installs these automatically via pip in a virtual environment.
 - *Rust*: example solvers using the preCICE [Rust bindings](https://precice.org/installation-bindings-rust.html). They need `cargo` to be installed.
 
+## Python callback interface tutorial track
+
+This case now includes a runnable callback variant matching the Python callback interface from the preCICE documentation:
+[configuration-action: Python callback interface](https://precice.org/configuration-action.html#python-callback-interface).
+
+The callback variant uses:
+
+- `precice-config-callback.xml` (adds `<action:python ...>` on `Solid`)
+- `solid-python/pressureRampAction.py` (defines `performAction(time, sourceData, targetData)`)
+- callback entry points `fluid-python/FluidSolverCallback.py` and `solid-python/SolidSolverCallback.py`
+
+### Goal
+
+Show a complete end-to-end callback setup while keeping the same physical model and participants.
+
+### Running the callback variant
+
+In two terminals:
+
+```bash
+cd solid-python
+bash run-callback.sh
+```
+
+```bash
+cd fluid-python
+bash run-callback.sh
+```
+
+This runs the same tube case with a Python action callback that ramps pressure for `t < 0.2`.
+
+### Compare callback vs baseline
+
+1. Baseline:
+
+   ```bash
+   cd solid-python && ./run.sh
+   cd fluid-python && ./run.sh
+   ```
+
+2. Callback variant:
+
+   ```bash
+   cd solid-python && bash run-callback.sh
+   cd fluid-python && bash run-callback.sh
+   ```
+
+3. Compare post-processing:
+
+   ```bash
+   ./plot-diameter.sh
+   ```
+
+You can inspect callback behavior by editing `solid-python/pressureRampAction.py`.
+
 ## Running the Simulation
 
 Choose one solver for each pariticipant, then open two separate terminals and start each soler by calling the respective run script.
diff --git a/elastic-tube-1d/fluid-python/FluidSolverCallback.py b/elastic-tube-1d/fluid-python/FluidSolverCallback.py
new file mode 100644
index 000000000..a7bf4c360
--- /dev/null
+++ b/elastic-tube-1d/fluid-python/FluidSolverCallback.py
@@ -0,0 +1,22 @@
+from __future__ import print_function
+
+import os
+import subprocess
+import sys
+
+
+def main():
+    here = os.path.dirname(os.path.abspath(__file__))
+    solver = os.path.join(here, "FluidSolver.py")
+    default_configuration = os.path.join(here, "..", "precice-config-callback.xml")
+
+    args = sys.argv[1:]
+    if len(args) == 0 or args[0].startswith("-"):
+        args = [default_configuration] + args
+
+    command = [sys.executable, solver] + args
+    subprocess.check_call(command)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/elastic-tube-1d/fluid-python/run-callback.sh b/elastic-tube-1d/fluid-python/run-callback.sh
new file mode 100644
index 000000000..f8d495047
--- /dev/null
+++ b/elastic-tube-1d/fluid-python/run-callback.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e -u
+
+. ../../tools/log.sh
+exec > >(tee --append "$LOGFILE") 2>&1
+
+if [ ! -v PRECICE_TUTORIALS_NO_VENV ]
+then
+    python3 -m venv .venv
+    . .venv/bin/activate
+    pip install -r requirements.txt && pip freeze > pip-installed-packages.log
+fi
+
+python3 ./FluidSolverCallback.py
+
+close_log
diff --git a/elastic-tube-1d/precice-config-callback.xml b/elastic-tube-1d/precice-config-callback.xml
new file mode 100644
index 000000000..56b7ab63a
--- /dev/null
+++ b/elastic-tube-1d/precice-config-callback.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<precice-configuration>
+  <log enabled="1">
+    <sink filter="%Severity% > debug" />
+  </log>
+
+  <profiling mode="fundamental" synchronize="false" />
+
+  <data:scalar name="Pressure" />
+  <data:scalar name="CrossSectionLength" />
+
+  <mesh name="Fluid-Nodes-Mesh" dimensions="2">
+    <use-data name="CrossSectionLength" />
+    <use-data name="Pressure" />
+  </mesh>
+
+  <mesh name="Solid-Nodes-Mesh" dimensions="2">
+    <use-data name="CrossSectionLength" />
+    <use-data name="Pressure" />
+  </mesh>
+
+  <participant name="Fluid">
+    <provide-mesh name="Fluid-Nodes-Mesh" />
+    <receive-mesh name="Solid-Nodes-Mesh" from="Solid" />
+    <write-data name="Pressure" mesh="Fluid-Nodes-Mesh" />
+    <read-data name="CrossSectionLength" mesh="Fluid-Nodes-Mesh" />
+    <mapping:nearest-neighbor
+      direction="read"
+      from="Solid-Nodes-Mesh"
+      to="Fluid-Nodes-Mesh"
+      constraint="consistent" />
+    <watch-point mesh="Fluid-Nodes-Mesh" name="Middle" coordinate="5; 0" />
+  </participant>
+
+  <participant name="Solid">
+    <provide-mesh name="Solid-Nodes-Mesh" />
+    <receive-mesh name="Fluid-Nodes-Mesh" from="Fluid" />
+    <write-data name="CrossSectionLength" mesh="Solid-Nodes-Mesh" />
+    <read-data name="Pressure" mesh="Solid-Nodes-Mesh" />
+    <mapping:nearest-neighbor
+      direction="read"
+      from="Fluid-Nodes-Mesh"
+      to="Solid-Nodes-Mesh"
+      constraint="consistent" />
+    <action:python mesh="Solid-Nodes-Mesh" timing="read-mapping-post">
+      <path name="." />
+      <module name="pressureRampAction" />
+      <source-data name="Pressure" />
+      <target-data name="Pressure" />
+    </action:python>
+  </participant>
+
+  <m2n:sockets acceptor="Fluid" connector="Solid" exchange-directory=".." />
+
+  <coupling-scheme:serial-implicit>
+    <participants first="Fluid" second="Solid" />
+    <max-time value="1.0" />
+    <time-window-size value="0.01" />
+    <max-iterations value="40" />
+    <exchange data="Pressure" mesh="Fluid-Nodes-Mesh" from="Fluid" to="Solid" />
+    <exchange
+      data="CrossSectionLength"
+      mesh="Solid-Nodes-Mesh"
+      from="Solid"
+      to="Fluid"
+      initialize="true" />
+    <relative-convergence-measure data="Pressure" mesh="Fluid-Nodes-Mesh" limit="1e-5" />
+    <relative-convergence-measure data="CrossSectionLength" mesh="Solid-Nodes-Mesh" limit="1e-5" />
+    <acceleration:IQN-ILS>
+      <data name="CrossSectionLength" mesh="Solid-Nodes-Mesh" />
+      <initial-relaxation value="0.01" />
+      <preconditioner type="residual-sum" update-on-threshold="false" />
+      <max-used-iterations value="50" />
+      <time-windows-reused value="8" />
+      <filter type="QR2" limit="1e-3" />
+    </acceleration:IQN-ILS>
+  </coupling-scheme:serial-implicit>
+</precice-configuration>
diff --git a/elastic-tube-1d/solid-python/SolidSolverCallback.py b/elastic-tube-1d/solid-python/SolidSolverCallback.py
new file mode 100644
index 000000000..46f71b5d4
--- /dev/null
+++ b/elastic-tube-1d/solid-python/SolidSolverCallback.py
@@ -0,0 +1,22 @@
+from __future__ import print_function
+
+import os
+import subprocess
+import sys
+
+
+def main():
+    here = os.path.dirname(os.path.abspath(__file__))
+    solver = os.path.join(here, "SolidSolver.py")
+    default_configuration = os.path.join(here, "..", "precice-config-callback.xml")
+
+    args = sys.argv[1:]
+    if len(args) == 0 or args[0].startswith("-"):
+        args = [default_configuration] + args
+
+    command = [sys.executable, solver] + args
+    subprocess.check_call(command)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/elastic-tube-1d/solid-python/pressureRampAction.py b/elastic-tube-1d/solid-python/pressureRampAction.py
new file mode 100644
index 000000000..e61340e7b
--- /dev/null
+++ b/elastic-tube-1d/solid-python/pressureRampAction.py
@@ -0,0 +1,7 @@
+from __future__ import division, print_function
+
+
+def performAction(time, sourceData, targetData):
+    timeThreshold = 0.2
+    ramp = min(time / timeThreshold, 1.0)
+    targetData[:] = ramp * sourceData
diff --git a/elastic-tube-1d/solid-python/run-callback.sh b/elastic-tube-1d/solid-python/run-callback.sh
new file mode 100644
index 000000000..7885fc468
--- /dev/null
+++ b/elastic-tube-1d/solid-python/run-callback.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e -u
+
+. ../../tools/log.sh
+exec > >(tee --append "$LOGFILE") 2>&1
+
+if [ ! -v PRECICE_TUTORIALS_NO_VENV ]
+then
+    python3 -m venv .venv
+    . .venv/bin/activate
+    pip install -r requirements.txt && pip freeze > pip-installed-packages.log
+fi
+
+python3 ./SolidSolverCallback.py
+
+close_log