feat: Model from StreamsContainer

[PProfizi]

This pull request adds support for constructing a Model directly from an existing StreamsContainer, improving performance and flexibility when working with file streams in DPF. It updates both the implementation and documentation to reflect this new capability, and introduces comprehensive tests to ensure correct behavior. The main changes are grouped below.

New feature: StreamsContainer support in Model

• src/ansys/dpf/core/model.py, src/ansys/dpf/core/_model_helpers.py: The Model class and its associated Metadata class now accept a StreamsContainer as input, in addition to DataSources and file paths. This allows users to avoid reopening file streams and enables sharing streams across multiple models or operators. [1] [2] [3]

Implementation details and resource management

• src/ansys/dpf/core/model.py, src/ansys/dpf/core/_model_helpers.py: Introduced internal properties and logic to distinguish between direct and internally-created streams, ensuring that streams provided by the user are not released by the Model destructor, while internally-created streams are properly cleaned up. [1] [2] [3]
• Updated methods that use streams to handle both direct StreamsContainer and operator-provided streams transparently. [1] [2] [3] [4] [5] [6]

Documentation updates

• src/ansys/dpf/core/model.py: Expanded docstrings and usage examples to document the new StreamsContainer input option for Model. [1] [2] [3]

Testing enhancements

• tests/test_model.py: Added a suite of tests to validate all aspects of the new StreamsContainer support, including construction, metadata access, results consistency, resource management, and correct handling of externally provided streams. [1] [2]

These changes make the Model class more flexible and efficient, especially in workflows involving multiple models or operators sharing the same file streams.

[codecov]

Codecov Report

❌ Patch coverage is 76.59574% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.84%. Comparing base (7372ff5) to head (c8d8143).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3095   +/-   ##
=======================================
  Coverage   82.84%   82.84%           
=======================================
  Files          93       93           
  Lines       11532    11568   +36     
=======================================
+ Hits         9554     9584   +30     
- Misses       1978     1984    +6