Improve description of flushing discharge

[jackvreeken]

Improved the overestimation of the exchange caused by a flushing discharge by introducing a constant factor of 0.82 to the flushing velocity (see equation 19 in section 2.1 of the documentation). Please check @mahoneyDeltares

@jackvreeken can you please check the workflow that updates the python library and the spreadsheet version of the ZSF now that we've migrated from GitLab?

[jackvreeken]

@maijvis Created a Draft PR for your changes, so they can be discussed more easily

[jackvreeken]

Some comments:

• Pipeline catches some style errors. It will also catch some test errors as well eventually (I think), as there are tests on expected mass fluxes.
• 0.82 is a lot like a magic number now. Either make it a named constant like FLUSHING_EFFECTIVENESS_FACTOR and/or create a new variable effective_velocity_flushing = FLUSHING_EFFECTIVENESS_FACTOR * velocity_flushing with a comment about why/based on what.
• The effectiveness of flushing can be better estimated with the factor of 0.82. But now you're also using it to effectively lengthen (?) the duration of "raw/unprotected" flushing when the bubble screen is not located exactly at the door. Is this indeed what you want? Operations cancel out. Never mind.

[maijvis]

The number is based on CFD validation. I think it might be best to make the flushing factor user definable with a default value of 1, agree @mahoneyDeltares?

What can I do about the style/test errors @jackvreeken?

[jackvreeken]

I'd say the default should be reasonable, and if that's 0.82 for most cases, then it should be 0.82.

As far as the style errors, you can take a look at the job that failed: https://github.com/Deltares/libzsf/actions/runs/4872318244/jobs/8690353188

If you want to fix them locally, you can run the command locally, and add a commit on top. The command that "fixes" the files is part of the CI pipeline, so if you ever forget it just go look here: https://github.com/Deltares/libzsf/blob/master/.github/workflows/ci.yml#L26 :)

So, install LLVM if you haven't already (see https://github.com/llvm/llvm-project/releases, or directly download https://github.com/llvm/llvm-project/releases/download/llvmorg-16.0.0/LLVM-16.0.0-win64.exe ). Then you can run the command locally, and it will fix the files.

Assuming you have a repository on your computer:

git fetch
git checkout flushing_effectiveness
# If you diverged from the origin, because I rebased your branch (which I really shouldn't do)
git reset --hard origin/flushing_effectiveness
# Run the command that fixes the files
clang-format -i src/* include/*
# add changes
git add -p
# make a commit
git commit -m "Style fixes"

When the pipeline succeeds, and we're about ready to merge, we can squash all the commits into one. Locally that means doing

# Interactively apply commits as fixups, but changing the "pick" to "f" or "s"
git rebase -i HEAD~10
# Force push, because diverging branches
git push -f 

I'm not sure how familiar you are with all this, so I can step in and do some of these things if you get stuck or don't quite know what to do. You don't have to learn everything all at once!

[jackvreeken]

Oh, one more general comment, it probably makes a lot of sense to change the docs in this PR as well if we're setting the default to 0.82 (or even introduce the option to change it). Maybe with some explanation on why (i.e. a summary of the results that led to this).