Refactor on DoMINO utils.py to improve code quality

[peterdsharpe]

PhysicsNeMo Pull Request

Major changes:

• Adds complete function docstrings with argument definitions, return type definitions, notes on what exceptions can raise, type hints, and example usages.
• Refactors to use pathlib.Path over os.path for file path management (preferred since Python 3.4) [1, 2]
• Fixes functions that have mutable default values (e.g., defaulting an argument to a list, rather than a tuple) - this should essentially-never be used, and leads to very-difficult-to-trace bugs.
• Removes a usage of from {package} import *, which is not necessary here and should essentially-never be used.
• Fixes missing requirements from DoMINO requirements.txt, to facilitate reproducible training
• Removes logic throughout that handled cases where PyVista/VTK/CuPy is not installed; this is unnecessary as the top level package dependencies already assert that these should be present (in "all"), and the pre-packaged container already contains these.
• Updates type hinting style to use latest Black/Ruff style recommendations for modern Python (e.g., list instead of from typing import List; use | rather than Union; prefer Type | None to Optional)
• Applies black formatting to utils.py, to bring it into compliance with repository-wide pre-commit hooks requirements. (Note: all future PRs should comply with this per CI, and we should not allow PRs to merge that bypass this check.)

Changes not yet implemented in this PR; these should be implemented in a future PR:

• DoMINO utils.py itself has no unit test coverage (and is only indirectly tested by the DoMINO forward pass test).
• Randomness in data processing and forward passes of model architectures should always be seeded for reproducibility; currently, it is not.
• Many VTK utilities could be refactored onto PyVista via pv.wrap(), which would reduce verbosity and help long-term maintainability.
• In DoMINO model.py, fixing instances that do torch.cat() on each iteration of Python-level for loops to incrementally append to tensors (we should instead build up a list[torch.Tensor] to cat all-at-once, or vectorize)

Description

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.
• The CHANGELOG.md is up to date with these changes.
• An issue is linked to this pull request.

Dependencies

[peterdsharpe]

Note: this PR should ideally be merged after #973; however, the changes are largely orthogonal between these two, so there should be minimal merge issues.

[peterdsharpe]

/blossom-ci

[coreyjadams]

Thanks for cleaning this up so extensively, @peterdsharpe . I have a few nits that will make our lives easier long term, but overall this looks great.

1. You have introduced a hard dependency on CUPY, which may be fine or maybe we want to avoid. If we do it, let's put it in requirements explicitly. (Its already there in the cuml dep)
2. Cupy has a built in array selection function - let's use that if we're requiring cupy and not have a wrapper.
3. You have made unit tests in the docstrings. That's 98% of the way to unit test in the test suite too, can we do that? They will both actually get tested, but it will help raise the test coverage bar a little.
4. For PyVista and VTK, what about factoring this utils.py file into two? One for pure-array and pure-python functions, and one which has an additional dependency on PV and VTK? This will allow more usage without those deps, which I think aren't needed once you have a preprocessed training set. As it stands, I think if someone handed me a curator-processed data set and I wanted to train DoMINO, I'd need VTK just to import some of these functions.

[peterdsharpe]

Tests added: daac91a

[peterdsharpe]

CuML hard-dependency removed: d2b11c7

[peterdsharpe]

/blossom-ci