B `@sdZddlmZddlmZddlmZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddlZddlmZddlmZddlmZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZddlmZddlm Z dgZ!ddddddddddddddd d!d"d#d$gZ"ddgZ#e$Z%d%Z&e'ej(Gd&d'd'ej)Z*d(d)Z+d*d+Z,d=d,d-Z-d.d/Z.d0d1Z/Gd2d3d3ej(Z0e'e0Gd4dde*Z1Gd5d6d6e2Z3d7d8Z4d9d:Z5d;d<Z6dS)>z+Base classes for probability distributions.)absolute_import)division)print_functionN)v2)kullback_leibler)slicing) assert_util)distribution_util) dtype_util) name_util)tensorshape_util)log1mexp)nest) tf_inspect Distribution batch_shapebatch_shape_tensorcdf covariance cross_entropyentropy event_shapeevent_shape_tensor kl_divergencelog_cdflog_problog_survival_functionmeanmodeprobsamplestddevsurvival_functionvarianceFc@seZdZdZdS)_BaseDistributionzsz$_update_docstring..cSs$g|]\}}|dkr|qS)zargs:)striplower)r;ixr<r)r)r* sz%_update_docstring..Nz )splitjoin enumerate)Zold_strZ append_strZ old_str_linesZ has_args_ixZ final_args_ixr)r)r*_update_docstringxs 0rFc stj|stj|r|dkr@fdd}tj||||ddS|dkrhfdd}tj||||ddSfdd}tj|||||ddd Stj|||d S) aConverts the given `value` to a (structure of) `Tensor`. This function converts Python objects of various types to a (structure of) `Tensor` objects. It accepts `Tensor` objects, numpy arrays, Python lists, and Python scalars. For example: Args: value: An object whose structure matches that of `dtype ` and/or `dtype_hint` and for which each leaf has a registered `Tensor` conversion function. dtype: Optional (structure of) element type for the returned tensor. If missing, the type is inferred from the type of `value`. dtype_hint: Optional (structure of) element type for the returned tensor, used when dtype is None. In some cases, a caller may not have a dtype in mind when converting to a tensor, so dtype_hint can be used as a soft preference. If the conversion to `dtype_hint` is not possible, this argument has no effect. name: Optional name to use if a new `Tensor` is created. Returns: tensor: A (structure of) `Tensor` based on `value`. Raises: TypeError: If no conversion function is registered for `value` to `dtype`. RuntimeError: If a registered conversion function returns an invalid value. ValueError: If the `value` is a tensor not of given `dtype` in graph mode. Ncstj||dS)N) dtype_hintr-)tfconvert_to_tensor)vdh)r-r)r*z$_convert_to_tensor..F) check_typescstj||dS)N)dtyper-)rHrI)rJd)r-r)r*rLrMcstj|||dS)N)rOrGr-)rHrI)rJrPrK)r-r)r*rLsT)rNZexpand_composites)rOrGr-)rHr is_nestedmap_structure_up_torI)valuerOrGr-r7r))r-r*_convert_to_tensors        rTcsfdd|DS)z4Removes `dict` keys which have have `self` as value.csi|]\}}|k r||qSr)r))r;krJ)valr)r* sz0_remove_dict_keys_with_value..)items)Zdict_rVr))rVr*_remove_dict_keys_with_valuesrYc Cs|tt|}t|j}t|}t|}t|}|dkrx|dk rx|dk rx|dk rx|||}t|dg||dk r|dk rt|dg||}t|||dk r|dk rtdg|||}t|||dk rx|dk r6|dkr|dk r|||}n |dkr6|dk r6|||}|dk rx|dk rxtdg||dg|}t|||S)zEHelper to `_set_sample_static_shape`; sets shape info for a `Tensor`.N)rH TensorShapeget_static_valuer rankshapeZ set_shapeZ concatenate) xrr sample_shapeZndimsZ sample_ndimsZ batch_ndimsZ event_ndimsr]r)r)r*#_set_sample_static_shape_for_tensors<           r`cs eZdZdZfddZZS)_DistributionMetaz&Helper metaclass for tfp.Distribution.cs|s tddd|D}|r&|dnd}|dks:|tkrPtt|||||St|tsltd||jxt D]}||krqrd|}| |d}t ||d} | st d|j|| |d} | dkrdnt | } | s|tkrt| }|||<| sqrt | } | dkr"td |j|t|jd || |_qrW| d ddkrhtt|||||Stjfd d } | |d <tt|||||S)aqControl the creation of subclasses of the Distribution class. The main purpose of this method is to properly propagate docstrings from private Distribution methods, like `_log_prob`, into their public wrappers as inherited by the Distribution base class (e.g. `log_prob`). Args: classname: The name of the subclass being created. baseclasses: A tuple of parent classes. attrs: A dict mapping new attributes to their values. Returns: The class object. Raises: TypeError: If `Distribution` is not a subclass of `BaseDistribution`, or the new class is derived via multiple inheritance and the first parent class is not a subclass of `BaseDistribution`. AttributeError: If `Distribution` does not implement e.g. `log_prob`. ValueError: If a `Distribution` public method lacks a docstring. zOExpected non-empty baseclass. Does Distribution not subclass _BaseDistribution?cSs"g|]}|tkst|tr|qSr))r$ issubclassr)r;baser)r)r*rAsz-_DistributionMeta.__new__..rNzEFirst parent class declared for {} must be Distribution, but saw "{}"z_{}zAInternal error: expected base class "{}" to implement method "{}"z4Expected base class fn to contain a docstring: {}.{}z'Additional documentation from `{}`: {}__init__csh~d|_|f|jdkrDt|fdd|_n t|jdrd|t|j||_dS)z-A 'master `__init__`' which is always called.NcsttjfS)N)rYinspect getcallargsr))args default_init dummy_selfkwargsr)r*rLVszA_DistributionMeta.__new__..wrapped_init..pop) _parameterstuple_no_dependencyhasattrrY)wrappedZself_rgrj)rh)rgrirjr* wrapped_initEs  z/_DistributionMeta.__new__..wrapped_init)r/r$superra__new__rbrr0r%$_DISTRIBUTION_PUBLIC_METHOD_WRAPPERSgetgetattrAttributeErrorrgetdoc#_ALWAYS_COPY_PUBLIC_METHOD_WRAPPERSr8 ValueErrorrFr( decorator)Zmcs classnameZ baseclassesattrsZ which_basercattrZ special_attrZclass_attr_valueZbase_attr_valueZclass_special_attr_valueZclass_special_attr_docstringZclass_attr_docstringrq) __class__)rhr*rss\                     z_DistributionMeta.__new__)r%r&r'r(rs __classcell__r)r))rr*rasracseZdZdZdfdd ZedddZedd Zed d Z e d d Z e ddZ e ddZ eddZddZddZe ddZe ddZe ddZddZd d!Zdd#d$Zd%d&Ze d'd(Zd)d*Zdd,d-Zd.d/Ze d0d1Zdd3d4Zdd6d7Zdd8d9Zd:d;Z dd>d?Z!d@dAZ"ddCdDZ#dEdFZ$ddHdIZ%dJdKZ&ddMdNZ'dOdPZ(ddRdSZ)dTdUZ*dVdWZ+ddYdZZ,d[d\Z-d]d^Z.dd`daZ/dbdcZ0ddedfZ1dgdhZ2ddjdkZ3dldmZ4dndoZ5ddqdrZ6dsdtZ7ddvdwZ8dxdyZ9dd{d|Z:d}d~Z;dddZddZ?dddZ@ddZAdddZBddZCddZDddZEddZFeGjHdeIdfddZJddZKddZLddZMddZNddZOZPS)raA generic probability distribution base class. `Distribution` is a base class for constructing and organizing properties (e.g., mean, variance) of random variables (e.g, Bernoulli, Gaussian). #### Subclassing Subclasses are expected to implement a leading-underscore version of the same-named function. The argument signature should be identical except for the omission of `name='...'`. For example, to enable `log_prob(value, name='log_prob')` a subclass should implement `_log_prob(value)`. Subclasses can append to public-level docstrings by providing docstrings for their method specializations. For example: ```python @distribution_util.AppendDocstring('Some other details.') def _log_prob(self, value): ... ``` would add the string "Some other details." to the `log_prob` function docstring. This is implemented as a simple decorator to avoid python linter complaining about missing Args/Returns/Raises sections in the partial docstrings. #### Broadcasting, batching, and shapes All distributions support batches of independent distributions of that type. The batch shape is determined by broadcasting together the parameters. The shape of arguments to `__init__`, `cdf`, `log_cdf`, `prob`, and `log_prob` reflect this broadcasting, as does the return value of `sample`. `sample_n_shape = [n] + batch_shape + event_shape`, where `sample_n_shape` is the shape of the `Tensor` returned from `sample(n)`, `n` is the number of samples, `batch_shape` defines how many independent distributions there are, and `event_shape` defines the shape of samples from each of those independent distributions. Samples are independent along the `batch_shape` dimensions, but not necessarily so along the `event_shape` dimensions (depending on the particulars of the underlying distribution). Using the `Uniform` distribution as an example: ```python minval = 3.0 maxval = [[4.0, 6.0], [10.0, 12.0]] # Broadcasting: # This instance represents 4 Uniform distributions. Each has a lower bound at # 3.0 as the `minval` parameter was broadcasted to match `maxval`'s shape. u = Uniform(minval, maxval) # `event_shape` is `TensorShape([])`. event_shape = u.event_shape # `event_shape_t` is a `Tensor` which will evaluate to []. event_shape_t = u.event_shape_tensor() # Sampling returns a sample per distribution. `samples` has shape # [5, 2, 2], which is [n] + batch_shape + event_shape, where n=5, # batch_shape=[2, 2], and event_shape=[]. samples = u.sample(5) # The broadcasting holds across methods. Here we use `cdf` as an example. The # same holds for `log_cdf` and the likelihood functions. # `cum_prob` has shape [2, 2] as the `value` argument was broadcasted to the # shape of the `Uniform` instance. cum_prob_broadcast = u.cdf(4.0) # `cum_prob`'s shape is [2, 2], one per distribution. No broadcasting # occurred. cum_prob_per_dist = u.cdf([[4.0, 5.0], [6.0, 7.0]]) # INVALID as the `value` argument is not broadcastable to the distribution's # shape. cum_prob_invalid = u.cdf([4.0, 5.0, 6.0]) ``` #### Shapes There are three important concepts associated with TensorFlow Distributions shapes: - Event shape describes the shape of a single draw from the distribution; it may be dependent across dimensions. For scalar distributions, the event shape is `[]`. For a 5-dimensional MultivariateNormal, the event shape is `[5]`. - Batch shape describes independent, not identically distributed draws, aka a "collection" or "bunch" of distributions. - Sample shape describes independent, identically distributed draws of batches from the distribution family. The event shape and the batch shape are properties of a Distribution object, whereas the sample shape is associated with a specific call to `sample` or `log_prob`. For detailed usage examples of TensorFlow Distributions shapes, see [this tutorial]( https://github.com/tensorflow/probability/blob/master/tensorflow_probability/examples/jupyter_notebooks/Understanding_TensorFlow_Distributions_Shapes.ipynb) #### Parameter values leading to undefined statistics or distributions. Some distributions do not have well-defined statistics for all initialization parameter values. For example, the beta distribution is parameterized by positive real numbers `concentration1` and `concentration0`, and does not have well-defined mode if `concentration1 < 1` or `concentration0 < 1`. The user is given the option of raising an exception or returning `NaN`. ```python a = tf.exp(tf.matmul(logits, weights_a)) b = tf.exp(tf.matmul(logits, weights_b)) # Will raise exception if ANY batch member has a < 1 or b < 1. dist = distributions.beta(a, b, allow_nan_stats=False) mode = dist.mode().eval() # Will return NaN for batch members with either a < 1 or b < 1. dist = distributions.beta(a, b, allow_nan_stats=True) # Default behavior mode = dist.mode().eval() ``` In all cases, an exception is raised if *invalid* parameters are passed, e.g. ```python # Will raise an exception if any Op is run. negative_a = -1.0 * a # beta distribution by definition has a > 0. dist = distributions.beta(negative_a, b, allow_nan_stats=True) dist.mean().eval() ``` Nc s|st|j}t|}t|}t|}tt|j|d||_ |dkrPgn|}x6t |D]*\}} | dksxt | s^t d|| fq^W||_||_||_||_|||_d|_||_tdd|jddD|_|jrt j|jf|_dS) aConstructs the `Distribution`. **This is a private method for subclass use.** Args: dtype: The type of the event samples. `None` implies no type-enforcement. reparameterization_type: Instance of `ReparameterizationType`. If `tfd.FULLY_REPARAMETERIZED`, then samples from the distribution are fully reparameterized, and straight-through gradients are supported. If `tfd.NOT_REPARAMETERIZED`, then samples from the distribution are not fully reparameterized, and straight-through gradients are either partially unsupported or are not supported at all. validate_args: Python `bool`, default `False`. When `True` distribution parameters are checked for validity despite possibly degrading runtime performance. When `False` invalid inputs may silently render incorrect outputs. allow_nan_stats: Python `bool`, default `True`. When `True`, statistics (e.g., mean, mode, variance) use the value "`NaN`" to indicate the result is undefined. When `False`, an exception is raised if one or more of the statistic's batch members are undefined. parameters: Python `dict` of parameters used to instantiate this `Distribution`. graph_parents: Python `list` of graph prerequisites of this `Distribution`. name: Python `str` name prefixed to Ops created by this class. Default: subclass name. Raises: ValueError: if any member of graph_parents is `None` or not a `Tensor`. )r-Nz)Graph parent item %d is not a Tensor; %s.Fcss|]}|dk r|VqdS)Nr))r;rPr)r)r*r=(sz(Distribution.__init__..T)is_init)typer%r Zcamel_to_lower_snakeZget_name_scope_nameZstrip_invalid_charsrrrrd_namerErHZ is_tensorrz_dtype_reparameterization_type_allow_nan_stats_validate_argsrnrl_parameters_sanitizedZ_graph_parentsrm_parameter_control_dependencies'_initial_parameter_control_dependenciesgroup) selfrOreparameterization_type validate_argsallow_nan_stats parametersZ graph_parentsr-it)rr)r*rds,&     zDistribution.__init__DistributionParamShapesc Cs t| ||SQRXdS)a,Shapes of parameters given the desired shape of a call to `sample()`. This is a class method that describes what key/value arguments are required to instantiate the given `Distribution` so that a particular shape is returned for that instance's call to `sample()`. Subclasses should override class method `_param_shapes`. Args: sample_shape: `Tensor` or python list/tuple. Desired shape of a call to `sample()`. name: name to prepend ops with. Returns: `dict` of parameter name to `Tensor` shapes. N)rH name_scope _param_shapes)clsr_r-r)r)r* param_shapes.s zDistribution.param_shapescCsxt|tjr(t|stdt|}||}i}x<|D]0\}}t |}|dkrbtdt|||<q@W|S)aparam_shapes with static (i.e. `TensorShape`) shapes. This is a class method that describes what key/value arguments are required to instantiate the given `Distribution` so that a particular shape is returned for that instance's call to `sample()`. Assumes that the sample's shape is known statically. Subclasses should override class method `_param_shapes` to return constant-valued tensors when constant values are fed. Args: sample_shape: `TensorShape` or python list/tuple. Desired shape of a call to `sample()`. Returns: `dict` of parameter name to `TensorShape`. Raises: ValueError: if `sample_shape` is a `TensorShape` and is not fully defined. z.TensorShape sample_shape must be fully definedNz>sample_shape must be a fully-defined TensorShape or list/tuple) isinstancerHrZr is_fully_definedrzas_listrrXr[)rr_paramsZ static_paramsr-r] static_shaper)r)r*param_static_shapesCs     z Distribution.param_static_shapescCs tddS)Nz_param_shapes not implemented)NotImplementedError)r_r)r)r*rjszDistribution._param_shapescCst|dr|jSdS)z9Name prepended to all ops created by this `Distribution`.rN)ror)rr)r)r*r-nszDistribution.namecCst|dr|jSdS)z8The `DType` of `Tensor`s handled by this `Distribution`.rN)ror)rr)r)r*rOsszDistribution.dtypecsVtdrjsLtjr"nj}fdd|D_d_tjS)zADictionary of parameters used to instantiate this `Distribution`.rcs(i|] \}}|ds|k r||qS)__) startswith)r;rUrJ)rr)r*rWsz+Distribution.parameters..T)rorr.rlrnrXdict)rpr))rr*rxs zDistribution.parameterscCstd|dS)aReturns a dict mapping constructor argument names to per-event rank. Distributions may implement this method to provide support for slicing (`__getitem__`) on the batch axes. Examples: Normal has scalar parameters, so would return `{'loc': 0, 'scale': 0}`. On the other hand, MultivariateNormalTriL has vector loc and matrix scale, so returns `{'loc': 1, 'scale_tril': 2}`. When a distribution accepts multiple parameterizations, either all possible parameters may be specified by the dict, e.g. Bernoulli returns `{'logits': 0, 'probs': 0}`, or if convenient only the parameters relevant to this instance may be specified. Parameter dtypes are inferred from Tensor attributes on the distribution where available, e.g. `bernoulli.probs`, 'mvn.scale_tril', falling back with a warning to the dtype of the distribution. Returns: params_event_ndims: Per-event parameter ranks, a `str->int dict`. zF{} does not support batch slicing; must implement _params_event_ndims.N)rr0)rr)r)r*_params_event_ndimssz Distribution._params_event_ndimscCst||i|S)a*Slices the batch axes of this distribution, returning a new instance. ```python b = tfd.Bernoulli(logits=tf.zeros([3, 5, 7, 9])) b.batch_shape # => [3, 5, 7, 9] b2 = b[:, tf.newaxis, ..., -2:, 1::2] b2.batch_shape # => [3, 1, 5, 2, 4] x = tf.random.stateless_normal([5, 3, 2, 2]) cov = tf.matmul(x, x, transpose_b=True) chol = tf.cholesky(cov) loc = tf.random.stateless_normal([4, 1, 3, 1]) mvn = tfd.MultivariateNormalTriL(loc, chol) mvn.batch_shape # => [4, 5, 3] mvn.event_shape # => [2] mvn2 = mvn[:, 3:, ..., ::-1, tf.newaxis] mvn2.batch_shape # => [4, 2, 3, 1] mvn2.event_shape # => [2] ``` Args: slices: slices from the [] operator Returns: dist: A new `tfd.Distribution` instance with sliced parameters. )r batch_slicer)rZslicesr)r)r* __getitem__szDistribution.__getitem__cCstdt|jdS)Nz{!r} object is not iterable)r/r0rr%)rr)r)r*__iter__szDistribution.__iter__cCs|jS)zDescribes how samples from the distribution are reparameterized. Currently this is one of the static instances `tfd.FULLY_REPARAMETERIZED` or `tfd.NOT_REPARAMETERIZED`. Returns: An instance of `ReparameterizationType`. )r)rr)r)r*rs z$Distribution.reparameterization_typecCs|jS)aPython `bool` describing behavior when a stat is undefined. Stats return +/- infinity when it makes sense. E.g., the variance of a Cauchy distribution is infinity. However, sometimes the statistic is undefined, e.g., if a distribution's pdf does not achieve a maximum within the support of the distribution, the mode is undefined. If the mean is undefined, then by definition the variance is undefined. E.g. the mean for Student's T for df = 1 is undefined (no clear way to say it is either + or - infinity), so the variance = E[(X - mean)**2] is also undefined. Returns: allow_nan_stats: Python `bool`. )r)rr)r)r*rszDistribution.allow_nan_statscCs|jS)z?Python `bool` indicating possibly expensive checks are enabled.)r)rr)r)r*rszDistribution.validate_argscKsVyt|||tStk rPt|jf|}t|f|}||_d|_ |SXdS)aCreates a deep copy of the distribution. Note: the copy distribution may continue to depend on the original initialization arguments. Args: **override_parameters_kwargs: String/value dictionary of initialization arguments to override with new values. Returns: distribution: A new instance of `type(self)` initialized from the union of self.parameters and override_parameters_kwargs, i.e., `dict(self.parameters, **override_parameters_kwargs)`. TN) rrrEllipsisrrrrrlr)rZoverride_parameters_kwargsrrPr)r)r*copys zDistribution.copycCstdt|jdS)Nz)batch_shape_tensor is not implemented: {})rr0rr%)rr)r)r*_batch_shape_tensorsz Distribution._batch_shape_tensorrc Cs||pt|jtjrdn|j}tddtj||jddDr\tj |t j |jdd}n| }tj |dd|ddSQRXdS)aShape of a single sample from a single event index as a 1-D `Tensor`. The batch dimensions are indexes into independent, non-identical parameterizations of this distribution. Args: name: name to give to the op Returns: batch_shape: `Tensor`. NcSsg|]}t|qSr))r r)r;sr)r)r*rAsz3Distribution.batch_shape_tensor..F)rNcSstjtj|tjdddS)N)rOr)r-)rHidentityrIint32)rr)r)r*rL#sz1Distribution.batch_shape_tensor..) _name_and_control_scoperrrHrZrOallrZ flatten_up_torRr rr)rr-Zshallow_structurerr)r)r*rs zDistribution.batch_shape_tensorcCsdS)Nr))rr)r)r* _batch_shape'szDistribution._batch_shapecCsL|}t|tjs,tddt|Dr6t|Stj|jtj|ddS)a)Shape of a single sample from a single event index as a `TensorShape`. May be partially defined or unknown. The batch dimensions are indexes into independent, non-identical parameterizations of this distribution. Returns: batch_shape: `TensorShape`, possibly unknown. css,|]$\}}t|dko"t|tj VqdS)N)lenrrHrZ)r;pathrr)r)r*r=;sz+Distribution.batch_shape..F)rN) rrrHrZrrZflatten_with_tuple_pathsrRrO)rrr)r)r*r*s   zDistribution.batch_shapecCstdt|jdS)Nz)event_shape_tensor is not implemented: {})rr0rr%)rr)r)r*_event_shape_tensorAsz Distribution._event_shape_tensorrc Csj||Vtddt|jDr@tj|jtj|jdd}n| }tj|jdd|ddSQRXdS)zShape of a single sample from a single batch as a 1-D int32 `Tensor`. Args: name: name to give to the op Returns: event_shape: `Tensor`. cSsg|]}t|qSr))r r)r;rr)r)r*rAOsz3Distribution.event_shape_tensor..F)rNcSstjtj|tjdddS)N)rOr)r-)rHrrIr)rr)r)r*rLYsz1Distribution.event_shape_tensor..N) rrrflattenrrRrOr rr)rr-rr)r)r*rEs zDistribution.event_shape_tensorcCsdS)Nr))rr)r)r* _event_shape]szDistribution._event_shapecCstj|jtj|ddS)zShape of a single sample from a single batch as a `TensorShape`. May be partially defined or unknown. Returns: event_shape: `TensorShape`, possibly unknown. F)rN)rrRrOrHrZr)rr)r)r*r`s zDistribution.event_shapeis_scalar_eventc Cs0||tj||j|jddSQRXdS)zIndicates that `event_shape == []`. Args: name: Python `str` prepended to names of ops created by this function. Returns: is_scalar_event: `bool` scalar `Tensor`. r)r-N)rrHrI_is_scalar_helperrr)rr-r)r)r*rls zDistribution.is_scalar_eventis_scalar_batchc Cs0||tj||j|jddSQRXdS)zIndicates that `batch_shape == []`. Args: name: Python `str` prepended to names of ops created by this function. Returns: is_scalar_batch: `bool` scalar `Tensor`. r)r-N)rrHrIrrr)rr-r)r)r*rzs zDistribution.is_scalar_batchcKstdt|jdS)Nzsample_n is not implemented: {})rr0rr%)rnseedrjr)r)r* _sample_nszDistribution._sample_nc Ks||tr |dkr tdtj|tjdd}||d\}}|j|fdt|rZ|n|i|}t |dd}t ||gd}t ||}| ||}|SQRXdS)zWrapper around _sample_n.Nz1Must provide JAX PRNGKey as `dist.sample(seed=.)`r_)r-rrr) rJAX_MODErzrHcastr_expand_sample_shape_to_vectorrr.r]concatZreshape_set_sample_static_shape) rr_rr-rjrZsamplesZbatch_event_shapeZ final_shaper)r)r*_call_sample_ns      zDistribution._call_sample_nr)r cKs|j|||f|S)aGenerate samples of the specified shape. Note that a call to `sample()` without arguments will generate a single sample. Args: sample_shape: 0D or 1D `int32` `Tensor`. Shape of the generated samples. seed: Python integer or `tfp.util.SeedStream` instance, for seeding PRNG. name: name to give to the op. **kwargs: Named arguments forwarded to subclass implementation. Returns: samples: a `Tensor` with prepended dimensions `sample_shape`. )r)rr_rr-rjr)r)r*r szDistribution.samplec Kszt|d|jd}||||Rt|dr8|j|f|St|drXtj|j|f|St d t |j WdQRXdS)zWrapper around _log_prob.rS)r-rG _log_prob_probzlog_prob is not implemented: {}N) rTrOrrorrHmathlogrrr0rr%)rrSr-rjr)r)r*_call_log_probs  zDistribution._call_log_probrcKs|j||f|S)auLog probability density/mass function. Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: log_prob: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*rs zDistribution.log_probc Ksxt|d|jd}||||Pt|dr8|j|f|St|drVt|j|f|Std t |j WdQRXdS)zWrapper around _prob.rS)r-rGrrzprob is not implemented: {}N) rTrOrrorrHexprrr0rr%)rrSr-rjr)r)r* _call_probs  zDistribution._call_probrcKs|j||f|S)amProbability density/mass function. Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: prob: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*rs zDistribution.probc Kszt|d|jd}||||Rt|dr8|j|f|St|drXtj|j|f|St d t |j WdQRXdS)zWrapper around _log_cdf.rS)r-rG_log_cdf_cdfzlog_cdf is not implemented: {}N) rTrOrrorrHrrrrr0rr%)rrSr-rjr)r)r* _call_log_cdfs  zDistribution._call_log_cdfrcKs|j||f|S)aLog cumulative distribution function. Given random variable `X`, the cumulative distribution function `cdf` is: ```none log_cdf(x) := Log[ P[X <= x] ] ``` Often, a numerical approximation can be used for `log_cdf(x)` that yields a more accurate answer than simply taking the logarithm of the `cdf` when `x << -1`. Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: logcdf: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*rszDistribution.log_cdfc Ksxt|d|jd}||||Pt|dr8|j|f|St|drVt|j|f|Std t |j WdQRXdS)zWrapper around _cdf.rS)r-rGrrzcdf is not implemented: {}N) rTrOrrorrHrrrr0rr%)rrSr-rjr)r)r* _call_cdfs  zDistribution._call_cdfrcKs|j||f|S)aCumulative distribution function. Given random variable `X`, the cumulative distribution function `cdf` is: ```none cdf(x) := P[X <= x] ``` Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: cdf: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*r szDistribution.cdfcKstdt|jdS)Nz,log_survival_function is not implemented: {})rr0rr%)rrSrjr)r)r*_log_survival_function!sz#Distribution._log_survival_functionc Kst|d|jd}||||zy|j|f|Stk r}zFt|dr\t|j|f|St|dr~tj |j |f| S|Wdd}~XYnXWdQRXdS)z&Wrapper around _log_survival_function.rS)r-rGrrN) rTrOrrrror rrHrlog1pr)rrSr-rjoriginal_exceptionr)r)r*_call_log_survival_function&s  z(Distribution._call_log_survival_functionrcKs|j||f|S)aLog survival function. Given random variable `X`, the survival function is defined: ```none log_survival_function(x) = Log[ P[X > x] ] = Log[ 1 - P[X <= x] ] = Log[ 1 - cdf(x) ] ``` Typically, different numerical approximations can be used for the log survival function, which are more accurate than `1 - cdf(x)` when `x >> 1`. Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*r3sz"Distribution.log_survival_functioncKstdt|jdS)Nz(survival_function is not implemented: {})rr0rr%)rrSrjr)r)r*_survival_functionMszDistribution._survival_functionc Kst|d|jd}||||zy|j|f|Stk r}zFt|drbtj|j |f| St|dr~d|j |f|S|Wdd}~XYnXWdQRXdS)z"Wrapper around _survival_function.rS)r-rGrrg?N) rTrOrrrrorHrexpm1rr)rrSr-rjrr)r)r*_call_survival_functionQs  z$Distribution._call_survival_functionr"cKs|j||f|S)a Survival function. Given random variable `X`, the survival function is defined: ```none survival_function(x) = P[X > x] = 1 - P[X <= x] = 1 - cdf(x). ``` Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*r"^szDistribution.survival_functioncKstdt|jdS)Nzentropy is not implemented: {})rr0rr%)rrjr)r)r*_entropytszDistribution._entropyrc Ks"|||jf|SQRXdS)zShannon entropy in nats.N)rr)rr-rjr)r)r*rxs zDistribution.entropycKstdt|jdS)Nzmean is not implemented: {})rr0rr%)rrjr)r)r*_mean}szDistribution._meanrc Ks"|||jf|SQRXdS)zMean.N)rr)rr-rjr)r)r*rs zDistribution.meancKstdt|jdS)Nzquantile is not implemented: {})rr0rr%)rrSrjr)r)r* _quantileszDistribution._quantilec Ks|||tj|jr tjn|j}tj|d|d}|jrxt t j |t d|jddt j |t d|jddg|}|j|f|SQRXdS)NrS)r-rGrz`value` must be <= 1)messagerz`value` must be >= 0)rrHrrQrOfloat32rIrr Zwith_dependenciesrZassert_less_equalrZassert_greater_equalr)rrSr-rjrOr)r)r*_call_quantiles zDistribution._call_quantilequantilecKs|j||f|S)aQuantile function. Aka 'inverse cdf' or 'percent point function'. Given random variable `X` and `p in [0, 1]`, the `quantile` is: ```none quantile(p) := x such that P[X <= x] == p ``` Args: value: `float` or `double` `Tensor`. name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: quantile: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type `self.dtype`. )r)rrSr-rjr)r)r*rszDistribution.quantilecKstdt|jdS)Nzvariance is not implemented: {})rr0rr%)rrjr)r)r* _varianceszDistribution._variancer#c Ksv||by |jf|Stk rf}z0yt|jf|Stk rT|YnXWdd}~XYnXWdQRXdS)a&Variance. Variance is defined as, ```none Var = E[(X - E[X])**2] ``` where `X` is the random variable associated with this distribution, `E` denotes expectation, and `Var.shape = batch_shape + event_shape`. Args: name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: variance: Floating-point `Tensor` with shape identical to `batch_shape + event_shape`, i.e., the same shape as `self.mean()`. N)rrrrHZsquare_stddev)rr-rjrr)r)r*r#s  zDistribution.variancecKstdt|jdS)Nzstddev is not implemented: {})rr0rr%)rrjr)r)r*rszDistribution._stddevr!c Ksv||by |jf|Stk rf}z0yt|jf|Stk rT|YnXWdd}~XYnXWdQRXdS)aCStandard deviation. Standard deviation is defined as, ```none stddev = E[(X - E[X])**2]**0.5 ``` where `X` is the random variable associated with this distribution, `E` denotes expectation, and `stddev.shape = batch_shape + event_shape`. Args: name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: stddev: Floating-point `Tensor` with shape identical to `batch_shape + event_shape`, i.e., the same shape as `self.mean()`. N)rrrrHsqrtr)rr-rjrr)r)r*r!s  zDistribution.stddevcKstdt|jdS)Nz!covariance is not implemented: {})rr0rr%)rrjr)r)r* _covarianceszDistribution._covariancerc Ks"|||jf|SQRXdS)aCovariance. Covariance is (possibly) defined only for non-scalar-event distributions. For example, for a length-`k`, vector-valued distribution, it is calculated as, ```none Cov[i, j] = Covariance(X_i, X_j) = E[(X_i - E[X_i]) (X_j - E[X_j])] ``` where `Cov` is a (batch of) `k x k` matrix, `0 <= (i, j) < k`, and `E` denotes expectation. Alternatively, for non-vector, multivariate distributions (e.g., matrix-valued, Wishart), `Covariance` shall return a (batch of) matrices under some vectorization of the events, i.e., ```none Cov[i, j] = Covariance(Vec(X)_i, Vec(X)_j) = [as above] ``` where `Cov` is a (batch of) `k' x k'` matrices, `0 <= (i, j) < k' = reduce_prod(event_shape)`, and `Vec` is some function mapping indices of this distribution's event dimensions to indices of a length-`k'` vector. Args: name: Python `str` prepended to names of ops created by this function. **kwargs: Named arguments forwarded to subclass implementation. Returns: covariance: Floating-point `Tensor` with shape `[B1, ..., Bn, k', k']` where the first `n` dimensions are batch coordinates and `k' = reduce_prod(self.event_shape)`. N)rr)rr-rjr)r)r*rs% zDistribution.covariancecKstdt|jdS)Nzmode is not implemented: {})rr0rr%)rrjr)r)r*_modeszDistribution._moderc Ks"|||jf|SQRXdS)zMode.N)rr)rr-rjr)r)r*rs zDistribution.modecCstj|||jdS)N)r)rrr)rotherr)r)r*_cross_entropy#szDistribution._cross_entropyrc Cs || ||SQRXdS)aComputes the (Shannon) cross entropy. Denote this distribution (`self`) by `P` and the `other` distribution by `Q`. Assuming `P, Q` are absolutely continuous with respect to one another and permit densities `p(x) dr(x)` and `q(x) dr(x)`, (Shannon) cross entropy is defined as: ```none H[P, Q] = E_p[-log q(X)] = -int_F p(x) log q(x) dr(x) ``` where `F` denotes the support of the random variable `X ~ P`. Args: other: `tfp.distributions.Distribution` instance. name: Python `str` prepended to names of ops created by this function. Returns: cross_entropy: `self.dtype` `Tensor` with shape `[B1, ..., Bn]` representing `n` different calculations of (Shannon) cross entropy. N)rr)rrr-r)r)r*r's zDistribution.cross_entropycCstj|||jdS)N)r)rrr)rrr)r)r*_kl_divergence@szDistribution._kl_divergencercCs ||S)apComputes the Kullback--Leibler divergence. Denote this distribution (`self`) by `p` and the `other` distribution by `q`. Assuming `p, q` are absolutely continuous with respect to reference measure `r`, the KL divergence is defined as: ```none KL[p, q] = E_p[log(p(X)/q(X))] = -int_F p(x) log q(x) dr(x) + int_F p(x) log p(x) dr(x) = H[p, q] - H[p] ``` where `F` denotes the support of the random variable `X ~ p`, `H[., .]` denotes (Shannon) cross entropy, and `H[.]` denotes (Shannon) entropy. Args: other: `tfp.distributions.Distribution` instance. name: Python `str` prepended to names of ops created by this function. Returns: kl_divergence: `self.dtype` `Tensor` with shape `[B1, ..., Bn]` representing `n` different calculations of the Kullback-Leibler divergence. )r)rrr-r)r)r*rDszDistribution.kl_divergencecCstdt|jdS)Nz5_default_event_space_bijector` is not implemented: {})rr0rr%)rr)r)r*_default_event_space_bijectoresz*Distribution._default_event_space_bijectorcCs|S)aBijector mapping the reals (R**n) to the event space of the distribution. Returns: event_space_bijector: `Bijector` instance or `None`. Distributions with continuous support have a `_default_event_space_bijector`, a subclass of `tfp.bijectors.Bijector` that maps R**n to the distribution's event space. For example, the `_default_event_space_bijector` of the `Beta` distribution is `tfb.Sigmoid()`, which maps the real line to `[0, 1]`, the support of the `Beta` distribution. The purpose of `_default_event_space_bijector` is to enable gradient descent in an unconstrained space for Variational Inference and Hamiltonian Monte Carlo methods. An effort has been made to choose bijectors such that the tails of the distribution in the unconstrained space are between Gaussian and Exponential. For distributions with discrete event space, `_default_event_space_bijector` returns `None`. )r)rr)r)r**_experimental_default_event_space_bijectorjsz7Distribution._experimental_default_event_space_bijectorcCsr|jrdt|j}nd}|jr0dt|j}nd}|jdk rNdt|j}nd}djt|j|jpfd|||dS)Nz, batch_shape=r9z, event_shape=z, dtype=z_tfp.distributions.{type_name}("{self_name}"{maybe_batch_shape}{maybe_event_shape}{maybe_dtype})z ) type_name self_namemaybe_batch_shapemaybe_event_shape maybe_dtype) r_str_tensorshaperrO _str_dtyper0rr%r-)rrrrr)r)r*__str__~s zDistribution.__str__cCs2djt|j|jpdt|jt|jt|jdS)Nzoz )rrrrrO) r0rr%r-rrrrrO)rr)r)r*__repr__s zDistribution.__repr__c cst|jt|z}g}||j||jdd|tk rd||j|f|dkr\in||sr|VdSt| }|VWdQRXWdQRXWdQRXdS)z(Helper function to standardize op scope.F)rN) rHrr-extendrr UNSET_VALUE_sample_control_dependenciesZcontrol_dependencies)rr-rSrjrdepsZ deps_scoper)r)r*rs   z$Distribution._name_and_control_scopecCsJt|}|dkrt|}ntj|t|jd}tj ||d}||fS)z-Helper to `sample` which ensures input is 1D.N)rO)Z tensor_name) rHr[Z reduce_prodnpprodr Zas_numpy_dtyperOr Zexpand_to_vector)rr^r-Z x_static_valrr)r)r*rs   z+Distribution._expand_sample_shape_to_vectorcsV|jtj|jr8tjs8tjfdd|jtjtjt|d||j S)z+Helper to `sample`; sets static shape info.csS)Nr))_)rr)r*rLrMz7Distribution._set_sample_static_shape..)r_) rrHrrQrO map_structure functoolspartialr`r)rr^r_r))rr*rs z%Distribution._set_sample_static_shapecCs`t|dk rt|dkS|}tj|jddk rJt|jdgkStt|ddS)z;Implementation for `is_scalar_batch` and `is_scalar_event`.Nr)r r\rHcompatZdimension_valuer]requal)rrZdynamic_shape_fnr]r)r)r*rs zDistribution._is_scalar_helpercCsdS)aReturns a list of ops to be executed in members with graph deps. Typically subclasses override this function to return parameter specific assertions (eg, positivity of `scale`, etc.). Args: is_init: Python `bool` indicating that the call site is `__init__`. Returns: dependencies: `list`-like of ops to be executed in member functions with graph dependencies. r)r))rrr)r)r*rs z,Distribution._parameter_control_dependenciescKsdS)a/Returns a list of ops to be executed to validate distribution samples. The ops are executed in methods that take distribution samples as an argument (e.g. `log_prob` and `cdf`). They validate that `value` is within the support of the distribution. Typically subclasses override this function to return assertions specific to the distribution (e.g. samples from `Beta` must be between `0` and `1`). By convention, finite bounds of the support are considered valid samples, since `sample` may output values that are numerically equivalent to the bounds. Args: value: `float` or `double` `Tensor`. **kwargs: Additional keyword args. Returns: assertions: `list`-like of ops to be executed in member functions that take distribution samples as input. r)r))rrSrjr)r)r*rsz)Distribution._sample_control_dependencies)NNN)r)r)r)r)r)N)r)Nr )r)r)r)r)r)r")r)r)r)r#)r!)r)r)r)r)Qr%r&r'r(rd classmethodrr staticmethodrpropertyr-rOrrrrrrrrrrrrrrrrrrrrr rrrrrrrrrrrrrr"rrrrrrrrr#rr!rrrrrrrrrrrr contextlibcontextmanagerrrrrrrrrr)r))rr*rds 9  '        #                  (   !    c@s eZdZdZddZddZdS) _PrettyDictz!`dict` with stable `repr`, `str`.cCs(ddt|D}dd|dS)Ncss(|] \}}dt|t|gVqdS)z: N)rDstr)r;rUrJr)r)r*r=sz&_PrettyDict.__str__..{z, })sortedrXrD)rpairsr)r)r*rsz_PrettyDict.__str__cCs(ddt|D}dd|dS)Ncss(|] \}}dt|t|gVqdS)z: N)rDrepr)r;rUrJr)r)r*r=sz'_PrettyDict.__repr__..rz, r)rrXrD)rrr)r)r*rsz_PrettyDict.__repr__N)r%r&r'r(rrr)r)r)r*rsrcCst|tr tdd|DSt|tjrt|tjsdd|D}t|tobt |dobt |d}|rtt ||St ||St|tj rt |fdd|DS|S)z/Recursively replace `dict`s with `_PrettyDict`.cSsi|]\}}t||qSr)))_recursively_replace_dict_for_pretty_dict)r;rUrJr)r)r*rWsz=_recursively_replace_dict_for_pretty_dict..css|]}t|VqdS)N)r)r;Zx_r)r)r*r=sz<_recursively_replace_dict_for_pretty_dict.._asdict_fieldscSsi|]\}}t||qSr))r)r;rUrJr)r)r*rWs) rrrrX collectionsSequencesix string_typesrmrorMapping)r^rgZis_named_tupler)r)r*r s       rcCs*dd}t|}ttj||ddS)NcSs(t|dkrdStt|ddS)N?None)r r\rrreplace)rr)r)r*_str!sz_str_tensorshape.._str'r9)rrrHrrr)r^rr)r)r*r srcCs*dd}t|}ttj||ddS)NcSs|dkr dSt|S)Nr)r r-)rr)r)r*r,sz_str_dtype.._strrr9)rrrHrrr)r^rr)r)r*r+sr)NNN)7r( __future__rrrabcr rrrer1r{numpyrr Z;tensorflow_probability.python.internal.backend.numpy.compatrrHZ2tensorflow_probability.python.distributions._numpyrZ;tensorflow_probability.python.distributions.internal._numpyrZ-tensorflow_probability.python.internal._numpyrr r r r Z1tensorflow_probability.python.math._numpy.genericr Z4tensorflow_probability.python.internal.backend.numpyrr__all__rtryobjectrr add_metaclassABCMetaModuler$r8rFrTrYr`rarrrrrrr)r)r)r*s                 0.s"