3
O4W^9%  ã               @   sº  d Z ddlZddlmZmZ dddgZG dd„ deƒZeƒ Zeƒ Z	ej
ejƒej
ejƒe	j
ejƒe	j
ejƒdd	„ ƒƒƒƒZej
ejƒe	j
ejƒd
d„ ƒƒZej
ejƒej
ejƒe	j
ejƒe	j
ejƒdd„ ƒƒƒƒZej
ejƒe	j
ejƒdd„ ƒƒZej
ejƒej
ejƒe	j
ejƒe	j
ejƒdd„ ƒƒƒƒZej
ejƒdd„ ƒZe	j
ejƒdd„ ƒZe	j
ejƒdd„ ƒZej
ejƒdd„ ƒZe	j
ejƒdd„ ƒZej
ej ƒdd„ ƒZ!e	j
ej ƒdd„ ƒZ"dS ) aF  
PyTorch provides two global :class:`ConstraintRegistry` objects that link
:class:`~torch.distributions.constraints.Constraint` objects to
:class:`~torch.distributions.transforms.Transform` objects. These objects both
input constraints and return transforms, but they have different guarantees on
bijectivity.

1. ``biject_to(constraint)`` looks up a bijective
   :class:`~torch.distributions.transforms.Transform` from ``constraints.real``
   to the given ``constraint``. The returned transform is guaranteed to have
   ``.bijective = True`` and should implement ``.log_abs_det_jacobian()``.
2. ``transform_to(constraint)`` looks up a not-necessarily bijective
   :class:`~torch.distributions.transforms.Transform` from ``constraints.real``
   to the given ``constraint``. The returned transform is not guaranteed to
   implement ``.log_abs_det_jacobian()``.

The ``transform_to()`` registry is useful for performing unconstrained
optimization on constrained parameters of probability distributions, which are
indicated by each distribution's ``.arg_constraints`` dict. These transforms often
overparameterize a space in order to avoid rotation; they are thus more
suitable for coordinate-wise optimization algorithms like Adam::

    loc = torch.zeros(100, requires_grad=True)
    unconstrained = torch.zeros(100, requires_grad=True)
    scale = transform_to(Normal.arg_constraints['scale'])(unconstrained)
    loss = -Normal(loc, scale).log_prob(data).sum()

The ``biject_to()`` registry is useful for Hamiltonian Monte Carlo, where
samples from a probability distribution with constrained ``.support`` are
propagated in an unconstrained space, and algorithms are typically rotation
invariant.::

    dist = Exponential(rate)
    unconstrained = torch.zeros(100, requires_grad=True)
    sample = biject_to(dist.support)(unconstrained)
    potential_energy = -dist.log_prob(sample).sum()

.. note::

    An example where ``transform_to`` and ``biject_to`` differ is
    ``constraints.simplex``: ``transform_to(constraints.simplex)`` returns a
    :class:`~torch.distributions.transforms.SoftmaxTransform` that simply
    exponentiates and normalizes its inputs; this is a cheap and mostly
    coordinate-wise operation appropriate for algorithms like SVI. In
    contrast, ``biject_to(constraints.simplex)`` returns a
    :class:`~torch.distributions.transforms.StickBreakingTransform` that
    bijects its input down to a one-fewer-dimensional space; this a more
    expensive less numerically stable transform but is needed for algorithms
    like HMC.

The ``biject_to`` and ``transform_to`` objects can be extended by user-defined
constraints and transforms using their ``.register()`` method either as a
function on singleton constraints::

    transform_to.register(my_constraint, my_transform)

or as a decorator on parameterized constraints::

    @transform_to.register(MyConstraintClass)
    def my_factory(constraint):
        assert isinstance(constraint, MyConstraintClass)
        return MyTransform(constraint.param1, constraint.param2)

You can create your own registry by creating a new :class:`ConstraintRegistry`
object.
é    N)ÚconstraintsÚ
transformsÚConstraintRegistryÚ	biject_toÚtransform_toc                   s2   e Zd ZdZ‡ fdd„Zd	dd„Zdd„ Z‡  ZS )
r   z5
    Registry to link constraints to transforms.
    c                s   i | _ tt| ƒjƒ  d S )N)Ú	_registryÚsuperr   Ú__init__)Úself)Ú	__class__© úH/tmp/pip-build-e66j97b2/torch/torch/distributions/constraint_registry.pyr	   S   s    zConstraintRegistry.__init__Nc                s`   |dkr‡ ‡fdd„S t ˆ tjƒr*tˆ ƒ‰ t ˆ tƒ sDtˆ tjƒ rRtdjˆ ƒƒ‚|ˆjˆ < |S )aþ  
        Registers a :class:`~torch.distributions.constraints.Constraint`
        subclass in this registry. Usage::

            @my_registry.register(MyConstraintClass)
            def construct_transform(constraint):
                assert isinstance(constraint, MyConstraint)
                return MyTransform(constraint.arg_constraints)

        Args:
            constraint (subclass of :class:`~torch.distributions.constraints.Constraint`):
                A subclass of :class:`~torch.distributions.constraints.Constraint`, or
                a singleton object of the desired class.
            factory (callable): A callable that inputs a constraint object and returns
                a  :class:`~torch.distributions.transforms.Transform` object.
        Nc                s   ˆj ˆ | ƒS )N)Úregister)Úfactory)Ú
constraintr
   r   r   Ú<lambda>j   s    z-ConstraintRegistry.register.<locals>.<lambda>zNExpected constraint to be either a Constraint subclass or instance, but got {})Ú
isinstancer   Z
ConstraintÚtypeÚ
issubclassÚ	TypeErrorÚformatr   )r
   r   r   r   )r   r
   r   r   W   s    
zConstraintRegistry.registerc             C   sD   y| j t|ƒ }W n( tk
r:   tdjt|ƒjƒƒ‚Y nX ||ƒS )aq  
        Looks up a transform to constrained space, given a constraint object.
        Usage::

            constraint = Normal.arg_constraints['scale']
            scale = transform_to(constraint)(torch.zeros(1))  # constrained
            u = transform_to(constraint).inv(scale)           # unconstrained

        Args:
            constraint (:class:`~torch.distributions.constraints.Constraint`):
                A constraint object.

        Returns:
            A :class:`~torch.distributions.transforms.Transform` object.

        Raises:
            `NotImplementedError` if no transform has been registered.
        zCannot transform {} constraints)r   r   ÚKeyErrorÚNotImplementedErrorr   Ú__name__)r
   r   r   r   r   r   Ú__call__w   s    zConstraintRegistry.__call__)N)r   Ú
__module__Ú__qualname__Ú__doc__r	   r   r   Ú__classcell__r   r   )r   r   r   O   s   
 c             C   s   t jS )N)r   Zidentity_transform)r   r   r   r   Ú_transform_to_real›   s    r   c             C   s   t jƒ S )N)r   ÚExpTransform)r   r   r   r   Ú_transform_to_positive£   s    r!   c             C   s   t jt jƒ t j| jdƒgƒS )Né   )r   ÚComposeTransformr    ÚAffineTransformÚlower_bound)r   r   r   r   Ú_transform_to_greater_than©   s    
r&   c             C   s   t jt jƒ t j| jdƒgƒS )Nr"   éÿÿÿÿ)r   r#   r    r$   Úupper_bound)r   r   r   r   Ú_transform_to_less_than²   s    
r)   c             C   sl   t | jtjƒo| jdk}t | jtjƒo.| jdk}|r@|r@tjƒ S | j}| j| j }tjtjƒ tj||ƒgƒS )Nr   r"   )	r   r%   ÚnumbersÚNumberr(   r   ZSigmoidTransformr#   r$   )r   Z
lower_is_0Z
upper_is_1ÚlocZscaler   r   r   Ú_transform_to_interval¹   s    
r-   c             C   s   t jƒ S )N)r   ZStickBreakingTransform)r   r   r   r   Ú_biject_to_simplexÊ   s    r.   c             C   s   t jƒ S )N)r   ZSoftmaxTransform)r   r   r   r   Ú_transform_to_simplexÏ   s    r/   c             C   s   t jƒ S )N)r   ZLowerCholeskyTransform)r   r   r   r   Ú_transform_to_lower_choleskyÕ   s    r0   c             C   s   t jdd„ | jD ƒ| j| jƒS )Nc             S   s   g | ]}t |ƒ‘qS r   )r   )Ú.0Úcr   r   r   ú
<listcomp>Ü   s   z"_biject_to_cat.<locals>.<listcomp>)r   ÚCatTransformÚcseqÚdimÚlengths)r   r   r   r   Ú_biject_to_catÚ   s    
r8   c             C   s   t jdd„ | jD ƒ| j| jƒS )Nc             S   s   g | ]}t |ƒ‘qS r   )r   )r1   r2   r   r   r   r3   ä   s   z%_transform_to_cat.<locals>.<listcomp>)r   r4   r5   r6   r7   )r   r   r   r   Ú_transform_to_catâ   s    
r9   c             C   s   t jdd„ | jD ƒ| jƒS )Nc             S   s   g | ]}t |ƒ‘qS r   )r   )r1   r2   r   r   r   r3   í   s   z$_biject_to_stack.<locals>.<listcomp>)r   ÚStackTransformr5   r6   )r   r   r   r   Ú_biject_to_stackê   s    r;   c             C   s   t jdd„ | jD ƒ| jƒS )Nc             S   s   g | ]}t |ƒ‘qS r   )r   )r1   r2   r   r   r   r3   ô   s   z'_transform_to_stack.<locals>.<listcomp>)r   r:   r5   r6   )r   r   r   r   Ú_transform_to_stackñ   s    r<   )#r   r*   Ztorch.distributionsr   r   Ú__all__Úobjectr   r   r   r   ÚrealZreal_vectorr   Zpositiver!   Úgreater_thanZgreater_than_eqr&   Ú	less_thanr)   ÚintervalZhalf_open_intervalr-   Zsimplexr.   r/   Zlower_choleskyr0   Úcatr8   r9   Ústackr;   r<   r   r   r   r   Ú<module>B   s>   D










