Archive and compare iterations.log for implicit coupling

[PranjalManhgaye]

Summary

Implicit coupling tutorials write precice-*-iterations.log files that show how many coupling iterations each time step needed. This PR adds system-test support to save those logs and check them against reference copies, so we notice when coupling behaviour changes unexpectedly. Closes #440.

Changes

• Systemtest.py: After a tutorial run, collect precice-*-iterations.log files into iterations-logs/ and compare them by SHA-256 hash against archived reference copies in a *.iterations-logs/ directory next to each reference .tar.gz. A successful check is logged at INFO; a mismatch fails the test.
• generate_reference_results.py: When you regenerate reference results, the iterations logs are copied into that *.iterations-logs/ folder so future runs have something to compare against.
• README.md: Documents the behaviour.
• changelog-entries/743.md: Changelog entry for this PR.

test (local)

Notes

• Tests without reference iterations logs skip comparison (unchanged tutorials).
• Explicit coupling (no iterations logs) is unaffected.

Checklist

• Changelog entry in changelog-entries/743.md

[precice-bot]

This pull request has been mentioned on preCICE Forum on Discourse. There might be relevant details there:

https://precice.discourse.group/t/gsoc-2026-pranjal-manhgaye/2769/5

[MakisH]

@PranjalManhgaye could you please resolve the merge conflicts and prepare this PR for reviewing?

[MakisH]

Some first comments. I have not yet looked at the complete PR or tested it.

[PranjalManhgaye]

thanks @MakisH for your review , i will make this pr review ready and also resolve conflicts .

[PranjalManhgaye]

Hi @MakisH , rebased onto develop, updated the PR description, and replied on your review threads. ready for another look when you have time.

[MakisH]

I have not yet completed my review, but here is already a first comment on something to check.

Tests I have executed locally:

• python3 systemtests.py --suites="openfoam_adapter_release" (no iterations in the reference results) succeeds
• python3 generate_reference_results.py --suites="openfoam_adapter_release" worked and generated results in an (uncompressed) folder flow-over-heated-plate/reference-results/fluid-openfoam_solid-openfoam.iterations-logs with fluid-openfoam/precice-Fluid-iterations.log and solid-openfoam/precice-Solid-iterations.log.
• after updating the reference results: python3 systemtests.py --suites="openfoam_adapter_release" worked, but I don't see sha256 or iterations in the output to confirm.

[PranjalManhgaye]

Hi @MakisH , pushed 095502d ; removed the JSON sidecar fallback and added INFO output when the iterations hash check passes.
Re-tested openfoam_adapter_release locally => same steps as you, and the second run now shows the INFO line.readme updated ,
Ready for another look when you can.

[MakisH]

Here are some first comments. Even though I would hope for a simpler/shorter solution, this is also fine, as it is rather clear.

You could merge back from develop now, I am through with the larger changes I wanted to do for now. And I think this would then be rather easy to merge and it would make sense to do it soon.

[PranjalManhgaye]

@MakisH i have resolved your initial comments and also merged develop , it is ready for another review thanks ,,

[MakisH]

A test run to see what happens for the current cases: https://github.com/precice/tutorials/actions/runs/28050285585/job/83038819578

Other than that, the documentation needs another look.

[MakisH]

Testing locally partially works, but it seems like the reference files are not added to the branch.

Testing on GHA

(not that important for now, read first the local testing)

A run without the iterations in the reference results shows that the check is correctly skipped when iterations logs are not in the reference data.

A run adding reference results logs that the iterations logs are archived in reference-results/fluid-cpp_solid-cpp.iterations-logs, and I see those in the runner.

A subsequent run still reports that iterations files are not found.

Testing locally

Testing locally, again with the elastic-tube-1d fluid-cpp/solid-cpp, I do see the the directory:

..../tutorials/elastic-tube-1d/reference-results [test-743]$ tree
.
├── fluid-cpp_solid-cpp.iterations-logs
│   ├── fluid-cpp
│   │   └── precice-Fluid-iterations.log
│   └── solid-cpp
│       └── precice-Solid-iterations.log
├── ...
└── reference_results.metadata

which is excluded by the .gitignore rules.

Why not place this directory directly in the respective fluid-cpp_solid-cpp.tar.gz? It could be a separate directory inside it than the one with the vtu files, in case that helps.

[PranjalManhgaye]

thanks for checking @MakisH , its correct if *.iterations-logs/ dirs are gitignored by *.log , so i will do it as you suggested and update the comparison logic accordingly

[MakisH]

Now the files are in the reference result archives, but fieldcompare fails:

field-compare-1  | [ FAILED  ] 2 file comparisons, listed below:
field-compare-1  | [ FAILED  ] iterations-logs/fluid-python/precice-Fluid-iterations.log: (Missing source file)
field-compare-1  | [ FAILED  ] iterations-logs/solid-python/precice-Solid-iterations.log: (Missing source file)

GHA run: https://github.com/precice/tutorials/actions/runs/28097293364

I think that having two separate directories in the archive would help. Ignoring specifically the iterations-logs/ directory in fieldcompare would also be fine, as it would be moving the iterations-logs/ outside the directory before running fieldcompare.

[PranjalManhgaye]

VTUs and iteration logs are now separate top-level tar members ({case}/ and {case}.iterations-logs/) ,so fieldcompare no longer hits log files in the VTU reference dir , verified locally , fieldcompare and hash check both pass ,refs will be regenerated on GHA ,,