Docstring for Potential function updated

pymc/model.py

@@ -2035,10 +2035,43 @@ def Deterministic(name, var, model=None, dims=None):
 def Potential(name, var, model=None):
     """Add an arbitrary factor potential to the model likelihood
 
+      Potential function is used to add arbitrary factors i.e. constraints that we define to the likelihood function of a model to adjust the probablity density of the model. 
+
+    .. code:: python
+
+        with pm.Model() as my_model:
+          x = pm.Normal('x', mu=0, tau=1)
+          y = pm.Normal('y', mu=x, tau=1)
+
+          constraint = x + y < 1
+          potential = pm.Potential('constraint', constraint, my_model)
+
+        In this example, we define a constraint on the sum of x and y that it can only be lesser than 1. We pass this constraint to the pm.Potential function.
+        Now the pm.Potential function takes in a expression, a scalar value and the model name as argument.
+        Now, the probablity density that the model produces takes into consideration the constraint that the sum of x and y should be lesser than 1.
+
+        The Potential function here acts as a gatekeeper allowing only samples that satisfy the constraint to contribute to the likelihood. This ensures that the sample generated by the sampler are consistent with the constraint.
+
+        Have a look at the following example:
+       
+     .. code:: python
+
+        with pm.Model() as model:
+          x = pm.Normal('x', mu=0, sigma=1)
+          y = pm.Normal('y',mu=x, sigma=1,observed=data)
+          constraint = x>= 0
+          potential = pm.Potential('x_constraint',-tt.log(tt.switch(constraint, 1, 1e-30)))
+
+        In this example, we define a constraint on x that it can be either greater than or equal to 0 and pass this constraint to the pm.Potential function.
+        Now the pm.Potential function takes in a string expression and a scalar value as argument. Hence we pass '-tt.log(tt.switch(constraint, 1, 1e-30))' as second argument which will return a scalar value depending on the constraint and will add to the likelihood function of the model.
+        This is done because PyMC3 uses an energy-based model, which means that the probability of a variable configuration is proportional to the negative of the energy of that configuration. So, the negative logarithm of the switch function ensures that the energy is high (i.e. close to negative infinity) when the constraint is not met, and low (i.e. close to zero) when the constraint is met.
+        The probablity density that this model produces agrees with the constraint that x should be greater than or equal to 0.
+
     Parameters
     ----------
     name: str
-    var: PyTensor variables
+    var: PyTensor or Scalar variables with the same shape as input to the likelihood
+    model: The model object to which the potential function is added. If none is provided, current model is used
 
     Returns
     -------