docs: added code examples in potential method docstring

[Jocho-Smith]

This PR is inspired by #1763

In preparation of GSoC Project Idea 3 I investigated into the potential functions and wrote minimal examples to try them out.

Is it appreciated if we add these examples in the class docstrings? In the same way it appeared in #1534, this would enhance API references on the docs website.

Pre-commit hooks and fast tests passed

(sbi) schmidt@node-63:~/gsoc2026/sbi$ pre-commit run --all-files
ruff.....................................................................Passed
ruff-format..............................................................Passed
check for added large files..............................................Passed
check for merge conflicts................................................Passed
check toml...............................................................Passed
check yaml...............................................................Passed
fix end of files.........................................................Passed
mixed line ending........................................................Passed
trim trailing whitespace.................................................Passed

(update: I just realized I could have just run pytest -m "not slow and not gpu", there was no need for --bm)

(sbi) schmidt@node-63:~/gsoc2026/sbi$ pytest --bm
....................                                     [100%]
====================== mini SBIBM results ======================
Amortized inference:
          gaussian_linear  linear_mvg_2d     slcp     two_moons  
-----------------------------------------------------------------
FMPE{}         0.608           0.525        0.950       0.799    
NLE_A{}        0.565           0.570        0.888       0.637    
NPE_C{}        0.558           0.637        0.950       0.789    
NPSE{}         0.635           0.512        0.904       0.733    
NRE_B{}        0.605           0.514        0.954       0.812    
20 passed in 844.00s (0:14:04)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.83%. Comparing base (cd69050) to head (920273d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1820   +/-   ##
=======================================
  Coverage   87.83%   87.83%           
=======================================
  Files         140      140           
  Lines       12958    12958           
=======================================
  Hits        11382    11382           
  Misses       1576     1576           

Flag	Coverage Δ
fast	82.67% <0.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

[Jocho-Smith]

I could also do that for the methods listed here: https://sbi.readthedocs.io/en/latest/api_reference/potentials.html

[dgedon]

I believe this is a very good start for the GSoC 2026 project 3 to get an overview. However, there are some issues:

• in the API reference we list the likelihood_estimator_based_potential function instead of the LikelihoodBasedPotential where your current examples are located. So they are never shown in the API reference
• more critical: the potentials are mostly used internally and have limited user-facing interaction. So examples have limited value
• With the re-design of the potential function, these examples would need a re-design as well.

Because of the second point, I think this PR is nice-to-have.

Changes that are necessary:

• add examples to the right location
• point out that the potentials can then be used for MCMC sampling, VI, ...

[Jocho-Smith]

Hello @dgedon, thanks for correcting me on this one! Looking back, I could have noticed this myself.

I understand your suggested changes and will implement them as soon as possible.

[Jocho-Smith]

Sorry for the long inactivity - I'll finally finish this, this week!

[Jocho-Smith]

mixed_likelihood_estimator_based_potential is mentioned in the documentation here, so I wanted to add an example to it too.

However, there is a deprecation warning in the code from 2 years ago.

When I try to use it in a minimal NLE example it fails (to me it looks like torch incompatibility)

code:

import torch
from sbi.inference import NLE, MCMCPosterior, mixed_likelihood_estimator_based_potential
from sbi.utils import BoxUniform

prior = BoxUniform(low=torch.zeros(3), high=torch.ones(3))
theta = prior.sample((100,))
x = theta + torch.randn_like(theta) * 0.1
x_o = torch.randn(1, 3)

trainer = NLE()
likelihood_estimator = trainer.append_simulations(theta, x).train()

potential_fn, parameter_transform = mixed_likelihood_estimator_based_potential(
    likelihood_estimator, prior, x_o
)
posterior = MCMCPosterior(
    potential_fn, proposal=prior, theta_transform=parameter_transform, warmup_steps=10
)

output:

(sbi) schmidt@node-63:~/gsoc2026/sbi$ python run.py 
/home/schmidt/gsoc2026/sbi/run.py:13: DeprecationWarning: This function is deprecated and will be removed in a future release. Use `likelihood_estimator_based_potential` instead.
  potential_fn, parameter_transform = mixed_likelihood_estimator_based_potential(
 Neural network successfully converged after 104 epochs.Traceback (most recent call last):
  File "/home/schmidt/gsoc2026/sbi/run.py", line 13, in <module>
    potential_fn, parameter_transform = mixed_likelihood_estimator_based_potential(
                                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/schmidt/gsoc2026/sbi/sbi/inference/potentials/likelihood_based_potential.py", line 371, in mixed_likelihood_estimator_based_potential
    device = str(next(likelihood_estimator.discrete_net.parameters()).device)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/schmidt/gsoc2026/sbi/.venv/lib/python3.12/site-packages/torch/nn/modules/module.py", line 1968, in __getattr__
    raise AttributeError(
AttributeError: 'NFlowsFlow' object has no attribute 'discrete_net'

The same example code worked without a problem for LikelihoodBasedPotential.

Now the question is where to go from here. Should I just ignore it for the example doc string? Or is there some symbiosis to my main gsoc project if I remove it from the codebase or even try to fix it?