Lazy eval refactor

[atbenmurray]

Lazy evaluation refactor

This PR contains a reworking of the lazy evaluation mechanism on dev to provide the following:

1. There are now three lazy execution options:
   1. the options=None (default) mode guarantees that all pending operations are evaluated before evaluating non-lazy _apply_transforms
      or transforms with lazy set to False. This means that all pipelines should be able to execute lazily without breaking (the first thing that users will try)
   2. there is an options={'reorder': 'lazy_last'} mode that moves all lazy operations past non-lazy ones, (bounded by use of
      ApplyPending/ApplyPendingd) and guarantees invertibility
   3. there is an options={'reorder': 'lazy_last_nosync'} mode that relies on ApplyPending/ApplyPendingd to cause application of
      pending transforms, and precisely mimics the behaviour of the lazy execution on dev.
2. Lazy now has three states on Compose:
   1. lazy=True overrides the lazy flag on lazy transforms, making them all execute lazily
   2. lazy=None uses the lazy flags set on transforms, and can execute them lazily or non-lazily depending
   3. lazy=False (default) causes lazy processing to be disabled and all lazy transforms will execute non-lazily
3. Lazy transforms have a lazy override that they can optionally set during __call__. This means that lazy behaviour can be overridden without mutating the transform instance
4. Logging has been fixed so that the first transform is included in the logging messages. Logging activities are clearer and contain addition important information about lazy modes
5. ApplyPending and ApplyPendingd replace the use of Identity and Identityd for causing pending ops to be evaluated when using the lazy_last[_nosync] options
6. Compose API changes:
   1. overrides and override_keys have been consolidated into overrides
      1. on dev: override_keys=('a', 'b'), overrides={'mode': ('bilinear', None), 'padding_mode: (None, 'zeros')'}
      2. on PR: overrides={'a': {'mode': 'bilinear'}, 'b': {'padding_mode': 'zeros'}}
   2. log_stats and verbose have been replaced with logger_name, consistent with other parts of MONAI
7. additional lazy resampling documentation has / is being added
8. additional lazy tests have been added

Types of changes

• Breaking changes:
  • lazy=True/None and options=None is new functionality relative to dev
  • lazy=True/None and options={"reorder": "lazy_last"} is new functionality relative to dev
  • lazy=None and setting lazy=True on a transform is new functionality relative to dev
  • Identity[d] doesn't cause pending operations to be evaluated; they must be replaced with ApplyPending[d]
• Non-breaking changes:
  • lazy=True and options={"reorder": "lazy_last_nosync"} (with Identity[d]being replaced byApplyPending[d]) should be identical in behaviour to dev`

• [wip] New tests added to cover the changes.
• Integration tests passed locally by running ./runtests.sh -f -u --net --coverage.
• Quick tests passed locally by running ./runtests.sh --quick --unittests --disttests.
• In-line docstrings updated.
• [wip] Documentation updated, tested make html command in the docs/ folder.

[wyli]

hi @atbenmurray sorry, earlier I didn't notice this PR is pending review. please address the merging conflicts I'll test and merge it. ApplyPending is better than implicit resampling calls in compose, and allows for flexible overriding.

[atbenmurray]

Gone through the merge from dev. I still need to test things before we merge!

[ericspod]

As we've discussed today at the meeting I'd suggest something like LazyPolicy given the current state of this class. If the intent is to evolve this to do more complicated work to "compile" in some manner we might want to put that into a new class anyway and keep something to do policy like this separate.

[ericspod]

Suggested change

	if invertible is False:
	if reasons is not None:
	reason_text = "\n".join(reasons)
	raise RuntimeError(f"Unable to run inverse on 'data' for the following reasons:\n{reason_text}")
	else:
	raise RuntimeError("Unable to run inverse on 'data'; no reason logged in trace data")
	if invertible is False:
	reason_text = "No reason logged in trace data" if reasons is None else "\n".join([""]+list(reasons))
	raise RuntimeError(f"Unable to run inverse on 'data': {reason_text}")

[Nic-Ma]

/build

[ericspod]

I would avoid having nested structures like this, instead:

Suggested change

	options = {"reorder": {"lazy_last": self.reorder_lazy_last, "lazy_last_nosync": self.reorder_lazy_last_nosync}}
	options = {("reorder","lazy_last"): self.reorder_lazy_last, ("reorder","lazy_last_nosync"): self.reorder_lazy_last_nosync}

Also the string keywords here should be in enums and the structure that's expected should be documented in the docstring.

[ericspod]

options is only ever used with one key-value pair so maybe just have two variables here. Otherwise eval_options or something, with more docstring on what it means.

[ericspod]

k, v = monai.utils.first(options.items())?

[ericspod]

Suggested change

	self.execution_options = ExecutionOptions()
	self.exec_options = ExecutionOptions() if exec_options is None else exec_options

[ericspod]

Suggested change

	def partially_lazy(self):
	def partially_lazy(self) -> bool:

[atbenmurray]

This is out of date. We'll revisit further lazy resampling functionality in new PRs. See #7151 for details