class_docstr: Bijector that approximates clipping as a continuous, differentiable map.
  
  The `forward` method takes unconstrained scalar `x` to a value `y` in
  `[low, high]`. For values within the interval and far from the bounds
  (`low << x << high`), this mapping is approximately the identity mapping.
  
  ```python
  b = tfb.SoftClip(low=-10., high=10.)
  b.forward([-15., -7., 1., 9., 20.])
    # => [-9.993284, -6.951412,  0.9998932,  8.686738,  9.999954 ]
  ```
  
  The softness of the clipping can be adjusted via the `hinge_softness`
  parameter. A sharp constraint (`hinge_softness < 1.0`) will approximate
  the identity mapping very well across almost all of its range, but may
  be numerically ill-conditioned at the boundaries. A soft constraint
  (`hinge_softness > 1.0`) corresponds to a smoother, better-conditioned
  mapping, but creates a larger distortion of its inputs.
  
  ```python
  b_hard = SoftClip(low=-5, high=5., hinge_softness=0.1)
  b_soft.forward([-15., -7., 1., 9., 20.])
    # => [-10., -7., 1., 8.999995,  10.]
  
  b_soft = SoftClip(low=-5, high=5., hinge_softness=10.0)
  b_soft.forward([-15., -7., 1., 9., 20.])
    # => [-6.1985435, -3.369276,  0.16719627,  3.6655345,  7.1750355]
  ```
  
  Note that the outputs are always in the interval `[low, high]`, regardless
  of the `hinge_softness`.
  
  #### Example use
  
  A trivial application of this bijector is to constrain the values sampled
  from a distribution:
  
  ```python
  dist = tfd.TransformedDistribution(
    distribution=tfd.Normal(loc=0., scale=1.),
    bijector=tfb.SoftClip(low=-5., high=5.))
  samples = dist.sample(100)  # => samples guaranteed in [-10., 10.]
  ```
  
  A more useful application is to constrain the values considered
  during inference, preventing an inference algorithm from proposing values
  that cause numerical issues. For example, this model will return a `log_prob`
  of `NaN` when `z` is outside of the range `[-5., 5.]`:
  
  ```python
  dist = tfd.JointDistributionNamed({
    'z': tfd.Normal(0., 1.0)
    'x': lambda z: tfd.Normal(
                     loc=tf.log(25 - z**2), # Breaks if z >= 5 or z <= -5.
                     scale=1.)})
  ```
  
  Using SoftClip allows us to keep an inference algorithm in the feasible
  region without distorting the inference geometry by very much:
  
  ```python
  target_log_prob_fn = lambda z: dist.log_prob(z=z, x=3.)  # Condition on x==3.
  
  # Use SoftClip to ensure sampler stays within the numerically valid region.
  mcmc_samples = tfp.mcmc.sample_chain(
    kernel=tfp.mcmc.TransformedTransitionKernel(
      tfp.mcmc.HamiltonianMonteCarlo(
        target_log_prob_fn=target_log_prob_fn,
        num_leapfrog_steps=2,
        step_size=0.1),
      bijector=tfb.SoftClip(-5., 5.)),
    trace_fn=None,
    current_state=0.,
    num_results=100)
  ```
  
  #### Mathematical Details
  
  The constraint is built by using `softplus(x) = log(1 + exp(x))` as a smooth
  approximation to `max(x, 0)`. In combination with affine transformations, this
  can implement a constraint to any scalar interval.
  
  In particular, translating `softplus` gives a generic lower bound constraint:
  
  ```
  max(x, low) =  max(x - low, 0) + low
              ~= softplus(x - low) + low
              := softlower(x)
  ```
  
  Note that this quantity is always greater than `low` because `softplus` is
  positive-valued. We can also implement a soft upper bound:
  
  ```
  min(x, high) =  min(x - high, 0) + high
               = -max(high - x, 0) + high
              ~= -softplus(high - x) + high
              := softupper(x)
  ```
  
  which, similarly, is always less than `high`.
  
  Composing these bounds as `softupper(softlower(x))` gives a quantity bounded
  above by `high`, and bounded below by `softupper(low)` (because `softupper`
  is monotonic and its input is bounded below by `low`). In general, we will
  have `softupper(low) < low`, so we need to shrink the interval slightly
  (by `(high - low) / (high - softupper(low))`) to preserve the lower bound.
  The two-sided constraint is therefore:
  
  ```python
  softclip(x) := (softupper(softlower(x)) - high) *
                   (high - low) / (high - softupper(low)) + high
               = -softplus(high - low - softplus(x - low)) *
                   (high - low) / (softplus(high-low)) + high
  ```
  
  Due to this rescaling, the bijector can be mildly asymmetric. Values
  of equal distance from the endpoints are mapped to values with slightly
  unequal distance from the endpoints; for example,
  
  ```python
  b = SoftConstrain(-1., 1.)
  b.forward([-0.5., 0.5.])
    # => [-0.2527727 ,  0.19739306]
  ```
  
  The degree of the asymmetry is proportional to the size of the rescaling
  correction, i.e., the extent to which `softupper` fails to be the identity
  map at the lower end of the interval. This is maximized when the upper and
  lower bounds are very close together relative to the hinge softness, as in
  the example above. Conversely, when the interval is wide, the required
  correction and asymmetry are very small.
class_docstr_tok: ["Bijector","that","approximates","clipping","as","a","continuous",",","differentiable","map",".","The","`","forward","`","method","takes","unconstrained","scalar","`","x","`","to","a","value","`","y","`","in","`","[","low",",","high","]","`",".","For","values","within","the","interval","and","far","from","the","bounds","(","`","low","<","<","x","<","<","high","`",")",",","this","mapping","is","approximately","the","identity","mapping",".","``","`","python","b","=","tfb.SoftClip","(","low=-10.",",","high=10",".",")","b.forward","(","[","-15.",",","-7.",",","1.",",","9.",",","20",".","]",")","#","=",">","[","-9.993284",",","-6.951412",",","0.9998932",",","8.686738",",","9.999954","]","``","`","The","softness","of","the","clipping","can","be","adjusted","via","the","`","hinge_softness","`","parameter",".","A","sharp","constraint","(","`","hinge_softness","<","1.0","`",")","will","approximate","the","identity","mapping","very","well","across","almost","all","of","its","range",",","but","may","be","numerically","ill-conditioned","at","the","boundaries",".","A","soft","constraint","(","`","hinge_softness",">","1.0","`",")","corresponds","to","a","smoother",",","better-conditioned","mapping",",","but","creates","a","larger","distortion","of","its","inputs",".","``","`","python","b_hard","=","SoftClip","(","low=-5",",","high=5.",",","hinge_softness=0.1",")","b_soft.forward","(","[","-15.",",","-7.",",","1.",",","9.",",","20",".","]",")","#","=",">","[","-10.",",","-7.",",","1.",",","8.999995",",","10",".","]","b_soft","=","SoftClip","(","low=-5",",","high=5.",",","hinge_softness=10.0",")","b_soft.forward","(","[","-15.",",","-7.",",","1.",",","9.",",","20",".","]",")","#","=",">","[","-6.1985435",",","-3.369276",",","0.16719627",",","3.6655345",",","7.1750355","]","``","`","Note","that","the","outputs","are","always","in","the","interval","`","[","low",",","high","]","`",",","regardless","of","the","`","hinge_softness","`",".","#","#","#","#","Example","use","A","trivial","application","of","this","bijector","is","to","constrain","the","values","sampled","from","a","distribution",":","``","`","python","dist","=","tfd.TransformedDistribution","(","distribution=tfd.Normal","(","loc=0.",",","scale=1",".",")",",","bijector=tfb.SoftClip","(","low=-5.",",","high=5",".",")",")","samples","=","dist.sample","(","100",")","#","=",">","samples","guaranteed","in","[","-10.",",","10",".","]","``","`","A","more","useful","application","is","to","constrain","the","values","considered","during","inference",",","preventing","an","inference","algorithm","from","proposing","values","that","cause","numerical","issues",".","For","example",",","this","model","will","return","a","`","log_prob","`","of","`","NaN","`","when","`","z","`","is","outside","of","the","range","`","[","-5.",",","5",".","]","`",":","``","`","python","dist","=","tfd.JointDistributionNamed","(","{","'","z","'",":","tfd.Normal","(","0.",",","1.0",")","'","x","'",":","lambda","z",":","tfd.Normal","(","loc=tf.log","(","25","-","z","*","*","2",")",",","#","Breaks","if","z",">","=","5","or","z","<","=","-5",".","scale=1",".",")","}",")","``","`","Using","SoftClip","allows","us","to","keep","an","inference","algorithm","in","the","feasible","region","without","distorting","the","inference","geometry","by","very","much",":","``","`","python","target_log_prob_fn","=","lambda","z",":","dist.log_prob","(","z=z",",","x=3",".",")","#","Condition","on","x==3",".","#","Use","SoftClip","to","ensure","sampler","stays","within","the","numerically","valid","region",".","mcmc_samples","=","tfp.mcmc.sample_chain","(","kernel=tfp.mcmc.TransformedTransitionKernel","(","tfp.mcmc.HamiltonianMonteCarlo","(","target_log_prob_fn=target_log_prob_fn",",","num_leapfrog_steps=2",",","step_size=0.1",")",",","bijector=tfb.SoftClip","(","-5.",",","5",".",")",")",",","trace_fn=None",",","current_state=0.",",","num_results=100",")","``","`","#","#","#","#","Mathematical","Details","The","constraint","is","built","by","using","`","softplus","(","x",")","=","log","(","1","+","exp","(","x",")",")","`","as","a","smooth","approximation","to","`","max","(","x",",","0",")","`",".","In","combination","with","affine","transformations",",","this","can","implement","a","constraint","to","any","scalar","interval",".","In","particular",",","translating","`","softplus","`","gives","a","generic","lower","bound","constraint",":","``","`","max","(","x",",","low",")","=","max","(","x","-","low",",","0",")","+","low","~=","softplus","(","x","-","low",")","+","low",":","=","softlower","(","x",")","``","`","Note","that","this","quantity","is","always","greater","than","`","low","`","because","`","softplus","`","is","positive-valued",".","We","can","also","implement","a","soft","upper","bound",":","``","`","min","(","x",",","high",")","=","min","(","x","-","high",",","0",")","+","high","=","-max","(","high","-","x",",","0",")","+","high","~=","-softplus","(","high","-","x",")","+","high",":","=","softupper","(","x",")","``","`","which",",","similarly",",","is","always","less","than","`","high","`",".","Composing","these","bounds","as","`","softupper","(","softlower","(","x",")",")","`","gives","a","quantity","bounded","above","by","`","high","`",",","and","bounded","below","by","`","softupper","(","low",")","`","(","because","`","softupper","`","is","monotonic","and","its","input","is","bounded","below","by","`","low","`",")",".","In","general",",","we","will","have","`","softupper","(","low",")","<","low","`",",","so","we","need","to","shrink","the","interval","slightly","(","by","`","(","high","-","low",")","\/","(","high","-","softupper","(","low",")",")","`",")","to","preserve","the","lower","bound",".","The","two-sided","constraint","is","therefore",":","``","`","python","softclip","(","x",")",":","=","(","softupper","(","softlower","(","x",")",")","-","high",")","*","(","high","-","low",")","\/","(","high","-","softupper","(","low",")",")","+","high","=","-softplus","(","high","-","low","-","softplus","(","x","-","low",")",")","*","(","high","-","low",")","\/","(","softplus","(","high-low",")",")","+","high","``","`","Due","to","this","rescaling",",","the","bijector","can","be","mildly","asymmetric",".","Values","of","equal","distance","from","the","endpoints","are","mapped","to","values","with","slightly","unequal","distance","from","the","endpoints",";","for","example",",","``","`","python","b","=","SoftConstrain","(","-1.",",","1",".",")","b.forward","(","[","-0.5.",",","0.5",".","]",")","#","=",">","[","-0.2527727",",","0.19739306","]","``","`","The","degree","of","the","asymmetry","is","proportional","to","the","size","of","the","rescaling","correction",",","i.e.",",","the","extent","to","which","`","softupper","`","fails","to","be","the","identity","map","at","the","lower","end","of","the","interval",".","This","is","maximized","when","the","upper","and","lower","bounds","are","very","close","together","relative","to","the","hinge","softness",",","as","in","the","example","above",".","Conversely",",","when","the","interval","is","wide",",","the","required","correction","and","asymmetry","are","very","small","."]
code: def hinge_softness(self):
      return self._hinge_softness
  
imports: import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import bijector
  from tensorflow_probability.python.bijectors import chain
  from tensorflow_probability.python.bijectors import scale
  from tensorflow_probability.python.bijectors import shift
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.internal import assert_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import parameter_properties
  from tensorflow_probability.python.internal import tensor_util
  from tensorflow_probability.python.util import deferred_tensor
label_desc: Use image node_id 5 for calling the SoftClip obj's underlying member method code with example usage: obj.hinge_softness() and returns: self