[com4]: allow executing FlowPy from a different repo with cfg overwrite

[PaulaSp3]

update:

• the return of the runCom4FlowPy.main() function is a dictionary containing:

  • "uid": id of simulation
  • "simulation": boolean: is the simulation is run
  • "resultOverwritten": boolean: are result files overwritten
  • "message": explanation to simulation status

• a simulation is executed, when there are no files in the results folder (with the same uid as the simulation that should be done)

• a flag overwriteResults is added,

  • if it is True result files are created although they already exist with same uid
  • (now, the file name contains the time stamp of the simulation, so the new result files do not overwrite the existing, they are added; do we want that or overwriting them? -> e.g. with deleting the timestamp in the file name or deleting the already existing result folder, and creating a new one within the simulation)

• added test

PR Checklist

Please confirm before requesting review:

• I ran pytest locally without fails
• I added/updated tests where needed
• I updated documentation where needed

Confirm before the final merge/rebase into master

• Commits are sensibly squashed and rebased onto latest master
• Standardtest run without difference (with recompiled cython code)

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on master by 3.20%.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	avaframe/in3Utils/fileHandlerUtils.py	100.0%
	avaframe/com4FlowPy/com4FlowPy.py	0.0%	424-796
	Total	94.7%

🤖 Increase coverage with AI coding...

In the `PS_FP_changeCfgRead` branch, add test coverage for this new code:

- `avaframe/com4FlowPy/com4FlowPy.py` -- Line 424-796

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[ahuber-bfw]

Good addition - should work as a quick hack and not break any current usage of the script.

For a more permanent solution I would suggest at least to address the following points:

• instead of just returning uid at every exit point of the function we can return sth. like a named tuple or dictionary with the uid and a function exit status, that lets the caller know if the function executed com4FlowPy successfully or did not run the model - because input was incorrect, result folders already exist --> see extra comment below
• write a small test that confirms the expected behavior of the functionality for different scenarios

in addition we could use this to think about how we want to handle the situation of already existing results with the same uid, which is currently also not solved well. Maybe we could:

• add an additional check, that also looks if the existing result folder with the uid is populated with valid resultFiles instead of just checking if the folder already exists (now this could also result from a previously started, but aborted model run) --> this would fix Issue #1135
• add an additional function parameter overwrite where the user can specify e.g. default --> don't run simulation if results with same uid already there; overwrite if sims should be performed any way

[ahuber-bfw]

tests schauen gut aus - dictionary als return passt auch.

• die Kommentare in runCom4FlowPy.py bitte noch anpassen
• der comment im .ini file ist als Diskussionspunkt gedacht (was meinst du?)

[ahuber-bfw]

some minor changes --> see comments

[ahuber-bfw]

schaut jetzt gut aus - 2-3 kleine Punkte noch:

• ich hab noch ein paar kleine Änderungen gepusht (fe1faa3)
• bitte für die neuen Funktionen im in3Utils/fileHandlerUtils noch jeweils einen Test ins entsprechende test_fileHandlerUtils file
• evtl. die Doku noch anpassen für den neuen overwrite Parameter im .ini

dann passts von meiner Seite :)

[ahuber-bfw]

pytests laufen alle durch
hab noch die Doku angepasst (vlt. kannst du da nochmal kurz drüber schauen @PaulaSp3)

commits sind gesquasht und rebased
von mir aus ready

[PaulaSp3]

standard tests ident (apart from snow glide test)