Commit b791e5a2 authored by Christoph Groth's avatar Christoph Groth Committed by Joseph Weston

builder: rename subs to substitute

parent 46dcc082
......@@ -24,24 +24,24 @@ would be washed out by the presence of the peak. Now `~kwant.plotter.map`
employs a heuristic for setting the colorscale when there are outliers,
and will emit a warning when this is detected.
System parameter names can be modified
--------------------------------------
After the introduction of ``Builder.fill`` it has become common to construct
System parameter substitution
-----------------------------
After the introduction of ``Builder.fill`` it has become possible to construct
Kwant systems by first creating a "model" system with high symmetry and then
filling a lower symmetry system with this model. Often, however, you want
to use different parameter values in different parts of your system. In
filling a lower symmetry system with this model. Often, however, one wants
to use different parameter values in different parts of a system. In
previous versions of Kwant this was difficult to achieve.
Builders now have a method ``subs`` that makes it easy to substitute different
names for parameters. For example if you have a Builder ``model`` that has
a parameter ``V``, and you wish to have different values for ``V`` in your
scattering region and leads you could do the following::
Builders now have a method ``substitute`` that makes it easy to substitute
different names for parameters. For example if a builder ``model``
has a parameter ``V``, and one wishes to have different values for ``V`` in
the scattering region and leads, one could do the following::
syst = kwant.Builder()
syst.fill(model.subs(V='V_dot', ...))
syst.fill(model.substitute(V='V_dot', ...))
lead = kwant.Builder()
lead.fill(model.subs(V='V_lead'), ...)
lead.fill(model.substitute(V='V_lead'), ...)
syst.attach_lead(lead)
fsyst = syst.finalized()
......
......@@ -1340,7 +1340,7 @@ class Builder:
self.update(other)
return self
def subs(self, **subs):
def substitute(self, **subs):
"""Return a copy of this Builder with modified parameter names.
"""
# Get value *functions* only
......
......@@ -1316,30 +1316,30 @@ def test_subs():
syst = make_system()
# substituting a paramter that doesn't exist produces a warning
warns(RuntimeWarning, syst.subs, fakeparam='yes')
warns(RuntimeWarning, syst.substitute, fakeparam='yes')
# name clash in value functions
raises(ValueError, syst.subs, b='a')
raises(ValueError, syst.subs, b='c')
raises(ValueError, syst.subs, a='site')
raises(ValueError, syst.subs, c='sitea')
# cannot call 'subs' on systems with attached leads, because
raises(ValueError, syst.substitute, b='a')
raises(ValueError, syst.substitute, b='c')
raises(ValueError, syst.substitute, a='site')
raises(ValueError, syst.substitute, c='sitea')
# cannot call 'substitute' on systems with attached leads, because
# it is not clear whether the substitutions should propagate
# into the leads too.
syst = make_system()
lead = make_system(kwant.TranslationalSymmetry((-1,)), n=1)
syst.attach_lead(lead)
raises(ValueError, syst.subs, a='d')
raises(ValueError, syst.substitute, a='d')
# test basic substitutions
syst = make_system()
expected = hamiltonian(syst, a=1, b=2, c=3)
# 1 level of substitutions
sub_syst = syst.subs(a='d', b='e')
sub_syst = syst.substitute(a='d', b='e')
assert np.allclose(hamiltonian(sub_syst, d=1, e=2, c=3), expected)
# 2 levels of substitution
sub_sub_syst = sub_syst.subs(d='g', c='h')
sub_sub_syst = sub_syst.substitute(d='g', c='h')
assert np.allclose(hamiltonian(sub_sub_syst, g=1, e=2, h=3), expected)
# very confusing but technically valid. 'a' does not appear in 'hopping',
# so the signature of 'onsite' is valid.
sub_syst = syst.subs(a='sitea')
sub_syst = syst.substitute(a='sitea')
assert np.allclose(hamiltonian(sub_syst, sitea=1, b=2, c=3), expected)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment