_once_ feature and documentation to instantiate

[swamidass]

Motivation

Sometimes we want to ensure a subtree of the config is instantiated only ONCE. Making unnecessary copies, in these cases, can hammer resources or even break code.

Take this example:

dataset:
  _target_: lightly.data.LightlyDataset
  root: data_dir
loader:
  _target_: torch.utils.data.DataLoader
  dataset: ${..dataset}  
  sampler:
    _target_: torch.utils.data.RandomSampler
    data_source: ${..dataset}.

Instantiating this config will, in fact, instantiate three separate instances of 'dataset', which is undesirable, because each one takes up memory. Even worse, calling instantiate a second time will create 3 more instances!

Pitch

I'd like this to be a built in feature of hydra (requiring just a minor version bump), using this syntax instead:

dataset:
  _target_: lightly.data.LightlyDataset
  _once_: true                     # instantiate will only create this tree once, reusing it when needed.
  _key_: unique_key # OPTIONAL: use this key, instead of the default hash of the yaml
  root: data_dir
loader:
  _target_: torch.utils.data.DataLoader
  dataset: ${..dataset}  
  sampler:
    _target_: torch.utils.data.RandomSampler
    data_source: ${..dataset}

This change is fully backwards compatible, and this PR passes all tests. It can be introduced initially beta in a patch release, or in a minor release.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

No special set up. Several tests added to tests/instantiate.py that verify correct behaivior. No existing tests fail. No existing behavior changes.

Related Issues and PRs

See feature request here: #3062

[swamidass]

For what it's worth, I've made the functionality available in a separately installable project:

https://github.com/swamidass/hydra-once