The use of save_hyperparameters() is currently confusing (due to name and docs)
📚 Documentation & function name change
The following documentation page is relevant here: https://pytorch-lightning.readthedocs.io/en/stable/weights_loading.html
The use of self.save_hyperparameters() is currently confusing for the following 3 reasons:

The role of this function is unclear. In the documentation this function is not mentioned once under the header "Checkpoint saving". Also, all arguments given to a LightningModule will be saved when calling trainer.save_checkpoint(), whether save_hyperparameters() has been used or not.
a. Edit: For example, are there any benefits of calling self.save_hyperparameters('arg1', 'arg3') over just assigning directly to self.hparams? E.g. like: self.hparams['arg1'] = arg1
The name save would indicate it is used to store the hyper parameters somewhere (e.g. disk). You would also expect that this function is not necessary when loading a .ckpt file (I don't want to change the self.hparams, and therefore do not want to save anything).
The documentation only mention this function under:


But if you don’t want to use the values saved in the checkpoint, pass in your own here

class LitModel(LightningModule):

    def __init__(self, in_dim, out_dim):
        super().__init__()
        self.save_hyperparameters()
        self.l1 = nn.Linear(self.hparams.in_dim, self.hparams.out_dim)
So my understanding of save_hyperparameters() was only to be used when you load a checkpoint AND want to overwrite the hyper parameters found in that checkpoint.
This resulted me being stuck in a "hparams not restored when loading ckpt" issue (https://forums.pytorchlightning.ai/t/hparams-not-restored-when-using-load-from-checkpoint-default-argument-values-are-the-problem/237) for longer than I would like to admit.
Possible solutions

Clarify why would like to use save_hyperparameters() over just not calling the function. Why was this function created? E.g. indicate that this moves arguments to self.hparams, which are used for automatic logging by e.g. Allegro TRAINS.
Change the name to something like init_hyperparameters() or arguments_to_hyperparameters().
Mention in documentation under Loading that this function is necessary to restore .ckpt hyperparameters.

End word
What are your thoughts about this?
Tagging
@Borda