Source code for pyro.params.param_store

# Copyright (c) 2017-2019 Uber Technologies, Inc.
# SPDX-License-Identifier: Apache-2.0

import re
import warnings
import weakref

import torch
from torch.distributions import constraints, transform_to

[docs]class ParamStoreDict: """ Global store for parameters in Pyro. This is basically a key-value store. The typical user interacts with the ParamStore primarily through the primitive `pyro.param`. See `Intro Part II <>`_ for further discussion and `SVI Part I <>`_ for some examples. Some things to bear in mind when using parameters in Pyro: - parameters must be assigned unique names - the `init_tensor` argument to `pyro.param` is only used the first time that a given (named) parameter is registered with Pyro. - for this reason, a user may need to use the `clear()` method if working in a REPL in order to get the desired behavior. this method can also be invoked with `pyro.clear_param_store()`. - the internal name of a parameter within a PyTorch `nn.Module` that has been registered with Pyro is prepended with the Pyro name of the module. so nothing prevents the user from having two different modules each of which contains a parameter named `weight`. by contrast, a user can only have one top-level parameter named `weight` (outside of any module). - parameters can be saved and loaded from disk using `save` and `load`. - in general parameters are associated with both *constrained* and *unconstrained* values. for example, under the hood a parameter that is constrained to be positive is represented as an unconstrained tensor in log space. """ # ------------------------------------------------------------------------------- # New dict-like interface def __init__(self): """ initialize ParamStore data structures """ self._params = {} # dictionary from param name to param self._param_to_name = {} # dictionary from unconstrained param to param name self._constraints = {} # dictionary from param name to constraint object
[docs] def clear(self): """ Clear the ParamStore """ self._params = {} self._param_to_name = {} self._constraints = {}
[docs] def items(self): """ Iterate over ``(name, constrained_param)`` pairs. Note that `constrained_param` is in the constrained (i.e. user-facing) space. """ for name in self._params: yield name, self[name]
[docs] def keys(self): """ Iterate over param names. """ return self._params.keys()
[docs] def values(self): """ Iterate over constrained parameter values. """ for name, constrained_param in self.items(): yield constrained_param
def __bool__(self): return bool(self._params) def __len__(self): return len(self._params) def __contains__(self, name): return name in self._params def __iter__(self): """ Iterate over param names. """ return iter(self.keys()) def __delitem__(self, name): """ Remove a parameter from the param store. """ unconstrained_value = self._params.pop(name) self._param_to_name.pop(unconstrained_value) self._constraints.pop(name) def __getitem__(self, name): """ Get the *constrained* value of a named parameter. """ unconstrained_value = self._params[name] # compute the constrained value constraint = self._constraints[name] constrained_value = transform_to(constraint)(unconstrained_value) constrained_value.unconstrained = weakref.ref(unconstrained_value) return constrained_value def __setitem__(self, name, new_constrained_value): """ Set the constrained value of an existing parameter, or the value of a new *unconstrained* parameter. To declare a new parameter with constraint, use :meth:`setdefault`. """ # store constraint, defaulting to unconstrained constraint = self._constraints.setdefault(name, constraints.real) # compute the unconstrained value with torch.no_grad(): # FIXME should we .detach() the new_constrained_value? unconstrained_value = transform_to(constraint).inv(new_constrained_value) unconstrained_value = unconstrained_value.contiguous() unconstrained_value.requires_grad_(True) # store a bidirectional mapping between name and unconstrained tensor self._params[name] = unconstrained_value self._param_to_name[unconstrained_value] = name
[docs] def setdefault(self, name, init_constrained_value, constraint=constraints.real): """ Retrieve a *constrained* parameter value from the if it exists, otherwise set the initial value. Note that this is a little fancier than :meth:`dict.setdefault`. If the parameter already exists, ``init_constrained_tensor`` will be ignored. To avoid expensive creation of ``init_constrained_tensor`` you can wrap it in a ``lambda`` that will only be evaluated if the parameter does not already exist:: param_store.get("foo", lambda: (0.001 * torch.randn(1000, 1000)).exp(), constraint=constraints.positive) :param str name: parameter name :param init_constrained_value: initial constrained value :type init_constrained_value: torch.Tensor or callable returning a torch.Tensor :param constraint: torch constraint object :type constraint: ~torch.distributions.constraints.Constraint :returns: constrained parameter value :rtype: torch.Tensor """ if name not in self._params: # set the constraint self._constraints[name] = constraint # evaluate the lazy value if callable(init_constrained_value): init_constrained_value = init_constrained_value() # set the initial value self[name] = init_constrained_value # get the param, which is guaranteed to exist return self[name]
# ------------------------------------------------------------------------------- # Old non-dict interface
[docs] def named_parameters(self): """ Returns an iterator over ``(name, unconstrained_value)`` tuples for each parameter in the ParamStore. Note that, in the event the parameter is constrained, `unconstrained_value` is in the unconstrained space implicitly used by the constraint. """ return self._params.items()
[docs] def get_all_param_names(self): warnings.warn("ParamStore.get_all_param_names() is deprecated; use .keys() instead.", DeprecationWarning) return self.keys()
[docs] def replace_param(self, param_name, new_param, old_param): warnings.warn("ParamStore.replace_param() is deprecated; use .__setitem__() instead.", DeprecationWarning) assert self._params[param_name] is old_param.unconstrained() self[param_name] = new_param
[docs] def get_param(self, name, init_tensor=None, constraint=constraints.real, event_dim=None): """ Get parameter from its name. If it does not yet exist in the ParamStore, it will be created and stored. The Pyro primitive `pyro.param` dispatches to this method. :param name: parameter name :type name: str :param init_tensor: initial tensor :type init_tensor: torch.Tensor :param constraint: torch constraint :type constraint: torch.distributions.constraints.Constraint :param int event_dim: (ignored) :returns: parameter :rtype: torch.Tensor """ if init_tensor is None: return self[name] else: return self.setdefault(name, init_tensor, constraint)
[docs] def match(self, name): """ Get all parameters that match regex. The parameter must exist. :param name: regular expression :type name: str :returns: dict with key param name and value torch Tensor """ pattern = re.compile(name) return {name: self[name] for name in self if pattern.match(name)}
[docs] def param_name(self, p): """ Get parameter name from parameter :param p: parameter :returns: parameter name """ return self._param_to_name.get(p)
[docs] def get_state(self): """ Get the ParamStore state. """ state = { 'params': self._params, 'constraints': self._constraints, } return state
[docs] def set_state(self, state): """ Set the ParamStore state using state from a previous get_state() call """ assert isinstance(state, dict), "malformed ParamStore state" assert set(state.keys()) == set(['params', 'constraints']), \ "malformed ParamStore keys {}".format(state.keys()) for param_name, param in state['params'].items(): self._params[param_name] = param self._param_to_name[param] = param_name for param_name, constraint in state['constraints'].items(): if isinstance(constraint, type(constraints.real)): # Work around lack of hash & equality comparison on constraints. constraint = constraints.real self._constraints[param_name] = constraint
[docs] def save(self, filename): """ Save parameters to disk :param filename: file name to save to :type filename: str """ with open(filename, "wb") as output_file:, output_file)
[docs] def load(self, filename, map_location=None): """ Loads parameters from disk .. note:: If using :meth:`pyro.module` on parameters loaded from disk, be sure to set the ``update_module_params`` flag:: pyro.get_param_store().load('') pyro.module('module', nn, update_module_params=True) :param filename: file name to load from :type filename: str :param map_location: specifies how to remap storage locations :type map_location: function, torch.device, string or a dict """ with open(filename, "rb") as input_file: state = torch.load(input_file, map_location) self.set_state(state)
# used to create fully-formed param names, e.g. mymodule$$$mysubmodule.weight _MODULE_NAMESPACE_DIVIDER = "$$$"
[docs]def param_with_module_name(pyro_name, param_name): return _MODULE_NAMESPACE_DIVIDER.join([pyro_name, param_name])
[docs]def module_from_param_with_module_name(param_name): return param_name.split(_MODULE_NAMESPACE_DIVIDER)[0]
[docs]def user_param_name(param_name): if _MODULE_NAMESPACE_DIVIDER in param_name: return param_name.split(_MODULE_NAMESPACE_DIVIDER)[1] return param_name