diff --git a/doc/source/code/figure/ab_ring.py.diff b/doc/source/code/figure/ab_ring.py.diff
index 50a10d1920c488552360b3bfc388d661da86d88f..c4fb178b462033ee9f0cdc906c4cfb5f349e403b 100644
--- a/doc/source/code/figure/ab_ring.py.diff
+++ b/doc/source/code/figure/ab_ring.py.diff
@@ -143,7 +143,7 @@
      normalized_fluxes = [flux / (2 * pi) for flux in fluxes]
      data = []
      for flux in fluxes:
-         smatrix = kwant.smatrix(syst, energy, args=[flux])
+         smatrix = kwant.smatrix(syst, energy, params=dict(phi=flux))
          data.append(smatrix.transmission(1, 0))
  
 -    pyplot.figure()
diff --git a/doc/source/code/figure/closed_system.py.diff b/doc/source/code/figure/closed_system.py.diff
index 5f9cc10122b239ebd33488bbc433868dbba02a55..6ad93be562a7e793ca1f825fa8af2ec5641ef114 100644
--- a/doc/source/code/figure/closed_system.py.diff
+++ b/doc/source/code/figure/closed_system.py.diff
@@ -68,7 +68,7 @@
      energies = []
      for B in Bfields:
          # Obtain the Hamiltonian as a dense matrix
-         ham_mat = syst.hamiltonian_submatrix(args=[B], sparse=True)
+         ham_mat = syst.hamiltonian_submatrix(params=dict(B=B), sparse=True)
  
          # we only calculate the 15 lowest eigenvalues
          ev = sla.eigsh(ham_mat.tocsc(), k=15, sigma=0,
@@ -105,7 +105,7 @@
 +    size = (_defs.figwidth_in, _defs.figwidth_in)
 +
      # Calculate the wave functions in the system.
-     ham_mat = syst.hamiltonian_submatrix(sparse=True, args=[B])
+     ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B))
      evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0))
  
      # Plot the probability density of the 10th eigenmode.
@@ -124,12 +124,12 @@
 +    size = (_defs.figwidth_in, _defs.figwidth_in)
 +
      # Calculate the wave functions in the system.
-     ham_mat = syst.hamiltonian_submatrix(sparse=True, args=[B])
+     ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B))
      evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0))
  
      # Calculate and plot the local current of the 10th eigenmode.
      J = kwant.operator.Current(syst)
-     current = J(evecs[:, 9], args=[B])
+     current = J(evecs[:, 9], params=dict(B=B))
 -    kwant.plotter.current(syst, current, colorbar=False)
 +    for extension in ('pdf', 'png'):
 +        kwant.plotter.current(
diff --git a/doc/source/code/figure/quantum_well.py.diff b/doc/source/code/figure/quantum_well.py.diff
index 1c81f1c54c37e24e231b15d6144c3cac7207e54e..8b1be4bb17cd8513816464e1782381842961ab88 100644
--- a/doc/source/code/figure/quantum_well.py.diff
+++ b/doc/source/code/figure/quantum_well.py.diff
@@ -59,7 +59,7 @@
      # Compute conductance
      data = []
      for welldepth in welldepths:
-         smatrix = kwant.smatrix(syst, energy, args=[-welldepth])
+         smatrix = kwant.smatrix(syst, energy, params=dict(pot=-welldepth))
          data.append(smatrix.transmission(1, 0))
  
 -    pyplot.figure()
diff --git a/doc/source/tutorial/discretize.rst b/doc/source/tutorial/discretize.rst
index 1ed5015cd2203e100d1d4e4cf9f21ae283716f04..b5edb0157f8a4ba5c3542b525328a48d852a8d42 100644
--- a/doc/source/tutorial/discretize.rst
+++ b/doc/source/tutorial/discretize.rst
@@ -160,9 +160,9 @@ energy eigenstates:
 
 .. image:: /code/figure/discretizer_gs.*
 
-Note in the above that we provided the function ``V`` to
-``syst.hamiltonian_submatrix`` using ``params=dict(V=potential)``, rather than
-via ``args``.
+Note in the above that we pass the spatially varying potential *function*
+to our system via a parameter called ``V``, because the symbol $V$
+was used in the intial, symbolic, definition of the Hamiltonian.
 
 In addition, the function passed as ``V`` expects two input parameters ``x``
 and ``y``, the same as in the initial continuum Hamiltonian.
diff --git a/doc/source/tutorial/spin_potential_shape.rst b/doc/source/tutorial/spin_potential_shape.rst
index bcf95dacc7627cf3822474009480287802cc6889..02ac1fbad566ad8daa570f26677e86c3d83fd01d 100644
--- a/doc/source/tutorial/spin_potential_shape.rst
+++ b/doc/source/tutorial/spin_potential_shape.rst
@@ -184,10 +184,12 @@ Finally, we compute the transmission probability:
     :start-after: #HIDDEN_BEGIN_sqvr
     :end-before: #HIDDEN_END_sqvr
 
-``kwant.smatrix`` allows us to specify a list, `args`, that will be passed as
-additional arguments to the functions that provide the Hamiltonian matrix
-elements.  In this example we are able to solve the system for different depths
-of the potential well by passing the potential value. We obtain the result:
+``kwant.smatrix`` allows us to specify a dictionary, `params`, that contains
+the additional arguments required by the Hamiltonian matrix elements.
+In this example we are able to solve the system for different depths
+of the potential well by passing the potential value (remember above
+we defined our `onsite` function that takes a parameter named `pot`).
+We obtain the result:
 
 .. image:: /code/figure/quantum_well_result.*