More consistent forward dose calculation and new dose engine tests

[wahln]

This pull request introduces significant improvements and new features to the particle pencil beam dose calculation engines in matRad, with a focus on more robust handling of bixel weight and monitor units (MU), improved air offset correction for particle therapy, and expanded test coverage for new and existing functionalities. The changes enhance both the accuracy and maintainability of the dose calculation codebase.

Dose Calculation Engine Improvements:

• Refactored bixel weight and MU handling: The code now consistently stores weight and MU in bixel and dij structures, and ensures these are properly propagated and ordered in resultGUI. This improves clarity and correctness in dose calculation for both direct and indirect dose computation modes. [1] [2] [3] [4] [5] [6] [7]

Steering and Air Offset Correction Enhancements:

• Added air offset correction for particle therapy: The matRad_StfGeneratorParticleIMPT class now supports an airOffsetCorrection property and applies a correction to the radiological depth calculation based on machine metadata, improving physical modeling accuracy for protons and heavier ions. [1] [2] [3] [4] [5] [6]

Testing and Quality Assurance:

• Introduced comprehensive test suites for new and existing particle pencil beam engines: Added test_HongPB.m and test_FSPB.m to thoroughly test engine instantiation, machine loading, dose calculation accuracy for various ion types, and error handling for unsupported or invalid settings. [1] [2]

Codebase Maintenance:

• Cleaned up legacy or redundant code: Removed unused variables and commented-out legacy functions to streamline the codebase and reduce maintenance overhead. [1] [2]

These changes collectively improve the accuracy, robustness, and maintainability of the particle pencil beam dose calculation workflow in matRad.

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 53.70%. Comparing base (1308623) to head (4801e1c).
⚠️ Report is 1 commits behind head on dev.

Files with missing lines	Patch %	Lines
matRad/steering/matRad_StfGeneratorParticleIMPT.m	81.25%	3 Missing ⚠️
...eEngines/matRad_ParticlePencilBeamEngineAbstract.m	75.00%	2 Missing ⚠️
...nes/@matRad_DoseEngineBase/matRad_DoseEngineBase.m	87.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #869      +/-   ##
==========================================
+ Coverage   53.32%   53.70%   +0.38%     
==========================================
  Files         307      307              
  Lines       19829    19844      +15     
==========================================
+ Hits        10574    10658      +84     
+ Misses       9255     9186      -69     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

Test Results

    3 files  ± 0      3 suites  ±0   43m 17s ⏱️ + 1m 0s
  311 tests +18    311 ✅ +18  0 💤 ±0  0 ❌ ±0 
1 029 runs  +54  1 024 ✅ +54  5 💤 ±0  0 ❌ ±0 

Results for commit 4801e1c. ± Comparison against base commit 1308623.

♻️ This comment has been updated with latest results.

[github-actions]

Package	Line Rate	Health
coverage Package 1	54%	➖
Summary	54% (10650 / 19844)	➖